Миграция с RevenueCat состоит из восьми шагов. Большую часть работы выполняет агент: он запускает миграцию через Adapty CLI и заменяет RevenueCat SDK в вашем приложении. Вы берёте на себя то, до чего агент не может добраться, — секреты и настройки в RevenueCat, App Store Connect и Google Cloud.

1. Изучите ключевые различия.
2. Перенесите каталог в Adapty.
3. Перенесите дизайны пейволов, если ваши офферинги станут флоу.
4. Замените RevenueCat SDK с помощью вашего coding agent.
5. Перенесите интеграции.
6. Настройте пересылку событий стора в Adapty.
7. Протестируйте и выпустите новую версию приложения.
8. (Опционально) Импортируйте историю транзакций.

Перед публикацией новой версии приложения с SDK Adapty обязательно ознакомьтесь с нашим чеклистом перед релизом.

Ознакомьтесь с основными отличиями

SDK Adapty и RevenueCat устроены похожим образом. Главное отличие — в работе с сетью и скорости: SDK Adapty разработан так, чтобы предоставлять нужную информацию по запросу максимально быстро. Например, при запросе пейвола вы сначала получаете Remote Config для предварительной сборки онбординга или пейвола, а затем в отдельном запросе запрашиваете продукты.

Названия немного отличаются:

RevenueCat	Adapty
Package	Продукт
Offering	Пейвол
Paywall	Флоу
Entitlement	Уровень доступа

В Adapty есть концепция плейсмента — логического места внутри приложения, где пользователь может совершить покупку. Как правило, плейсментов один или два:

• Онбординг (80% всех покупок происходят именно там);
• Общий (показывается в настройках или внутри приложения после онбординга).

Перенос каталога в Adapty

Миграция каталога создаёт новое приложение в Adapty на основе вашего проекта RevenueCat: уровни доступа из entitlements, продукты из пакетов и плейсмент с пейволом или флоу для каждого offering.

Перед началом работы

• Используйте агента для написания кода, который может выполнять команды в терминале, например Claude Code, Codex или Cursor.
• В терминале, который использует агент, установите Adapty CLI и войдите в систему.
• В RevenueCat создайте секретный API-ключ (v2) для проекта, который вы переносите.
• Проверьте сторы. Миграция поддерживает только приложения из App Store и Google Play.

Создайте секретный API-ключ RevenueCat

Adapty читает каталог RevenueCat с помощью секретного API-ключа проекта, из которого вы переходите. В RevenueCat секретные ключи принадлежат конкретному проекту, поэтому создайте ключ именно в нём.

1. Чтобы открыть список ключей, в дашборде RevenueCat откройте проект и перейдите в API keys.
2. Чтобы создать ключ, нажмите New secret API key.
3. Чтобы настроить ключ, введите название, например Adapty migration, и выберите V2 в поле API version.
4. Чтобы Adapty мог читать каталог, установите Project configuration permissions в значение Read only. Другие разрешения Adapty не нужны.
5. Чтобы создать ключ, нажмите Generate и скопируйте его.

Когда в процессе миграции потребуется ключ, вставьте его на открывшейся странице дашборда Adapty.

Запустите миграцию каталога

1. Чтобы начать миграцию, попросите агента:

   Migrate my RevenueCat project to a new Adapty app called "Acme Fitness" with the Adapty CLI.

2. Чтобы подключить RevenueCat, вставьте секретный API-ключ на страницу дашборда Adapty, которую открывает агент. Ключ поступает напрямую в Adapty и никогда не проходит через агента или CLI.

3. Чтобы выбрать, что мигрировать, сообщите агенту, какие приложения RevenueCat относятся к одному продукту — как правило, по одному на каждую платформу. Вместе они станут одним приложением в Adapty.

4. Чтобы согласовать маппинг, ответьте на вопросы агента об объектах, которые Adapty не смог сопоставить самостоятельно. Для каждого офферинга выберите, что будет в его плейсменте: пейвол, который ваше приложение отрисовывает самостоятельно, или флоу из Flow & Paywall Builder. Adapty предлагает флоу для офферингов с пейволом RevenueCat.

   Warning

   Решения окончательны. Когда для каждой сущности принято решение, Adapty создаёт каталог, и изменить маппинг после этого невозможно.

   Adapty создаёт уровни доступа, продукты, пейволы и флоу, а также плейсменты — именно в таком порядке. Если что-то из этого не удаётся создать, агент сообщит причину. Когда все сущности появятся в Adapty, миграция считается завершённой.

5. Чтобы новое приложение могло валидировать покупки, подключите его к сторам в дашборде Adapty: App Store и Google Play.

Как сущности RevenueCat соотносятся с Adapty

• Идентификатор entitlement становится ID уровня доступа, поэтому customerInfo.entitlements["premium"] превращается в profile.accessLevels["premium"].
• Продукт, не привязанный ни к одному entitlement, получает уровень доступа premium.
• Идентификатор offering становится ID плейсмента.
• Метаданные offering становятся Remote Config пейвола или флоу, объёмом до 256 КБ.

Что не переносит миграция каталога

• Офферинги без продуктов.
• Продукты, App Store product ID которых Adapty отклоняет — например, ID с двоеточием или пробелом. Агент сообщает, какие именно, и никаких решений от вас не требуется.
• Приложения в сторах, отличных от App Store и Google Play.
• Интеграции: перенесите их отдельно.

Перенесите дизайны пейволов

Каждый флоу, созданный при миграции каталога, публикуется с пустым экраном поверх продуктов оффера. Чтобы перестроить дизайны пейволов из RevenueCat в этих флоу, попросите агента:

Migrate my RevenueCat paywall designs to my Adapty app "Acme Fitness" with the Adapty CLI.

Агент перестраивает флоу по одному и публикует каждый после вашего подтверждения. Он перечисляет то, что нужно добавить вручную, — например, видео и кастомные шрифты. Дизайны читаются с помощью вашего секретного API-ключа RevenueCat, поэтому не удаляйте его, пока перенос не завершён.

Замена SDK RevenueCat

Агент кодирования заменяет SDK RevenueCat на SDK Adapty в коде вашего приложения, используя ID из каталога, созданного в ходе миграции. Каждый запуск мигрирует одну кодовую базу: если у вас отдельные проекты для iOS и Android, запустите его в каждом из них.

Прежде чем начать, закоммитьте или спрячьте в stash изменения в репозитории приложения — тогда миграция останется одним читаемым диффом.

1. Чтобы начать миграцию кода, откройте агент в корне репозитория приложения и введите:

   Migrate the app code in this repository from RevenueCat to Adapty with the Adapty CLI, for my Adapty app "Acme Fitness".

   If the agent asks you to restart it to load the Adapty skills, restart it and repeat the request.

2. If a flow’s design isn’t moved yet, tell the agent whether the app shows the flow or keeps its own paywall screen until then.

3. To finish the code migration, review the changes on the adapty-migrate branch, then work through ADAPTY_SETUP.md in the root of your project. It lists what the agent left to you.

Перенесите ваши интеграции

Агент находит в коде вашего приложения инструменты аналитики, атрибуции и рассылок и объясняет, как настроить каждый из них в Adapty. Никаких файлов он не изменяет. Спросите:

Find the integrations in my app code to set up in my Adapty app "Acme Fitness", with the Adapty CLI.

Если в репозитории есть код только для одной платформы, укажите агенту, где находится код для другой. Затем настройте интеграции, как описано в Перенос интеграций в Adapty. Вебхуки, Slack и экспорт в облачное хранилище не находятся в коде приложения: их можно найти на странице Integrations в RevenueCat.

Перенаправьте события стора в Adapty

App Store и Google Play сообщают о продлениях, отменах и возвратах на ваш сервер через уведомления — в том числе те, что происходят за пределами приложения. Два сценария миграции подключают Adapty к этим уведомлениям, при этом RevenueCat продолжает получать все события, так что обе системы остаются актуальными, пока ваши пользователи переходят на новую версию приложения.

Запустите их после завершения миграции каталога. Adapty автоматически возьмёт bundle ID и package name из выбранных вами приложений RevenueCat.

Пересылка событий App Store

Adapty получает уведомления от App Store и пересылает каждое из них в RevenueCat.

Перед началом создайте ключ In-App Purchase в App Store Connect и сохраните его Issuer ID и Key ID.

1. Чтобы начать пересылку, обратитесь к агенту:

   Forward App Store events for my Adapty app "Acme Fitness" to Adapty, and keep RevenueCat receiving them.

2. Чтобы предоставить Adapty доступ к событиям App Store, загрузите файл .p8 на открытую агентом страницу дашборда Adapty, а также введите Issuer ID и Key ID. Ключ передаётся напрямую в Adapty — через агент или CLI он не проходит.

3. Чтобы RevenueCat продолжал получать события App Store, передайте агенту URL уведомлений RevenueCat. В RevenueCat откройте своё iOS-приложение и скопируйте Apple Server Notification URL из раздела Apple Server to Server notification settings. Он начинается с https://api.revenuecat.com/v1/incoming-webhooks/.

4. Чтобы направить App Store на Adapty, откройте своё приложение в App Store Connect и перейдите в App Information > App Store Server Notifications. Установите и Production Server URL, и Sandbox Server URL на URL Adapty, который вам предоставит агент, выбрав уведомления Version 2. Подробнее см. в разделе Включение серверных уведомлений App Store. Пересылка в RevenueCat уже настроена на этом этапе, поэтому ни одно событие не теряется.

5. Чтобы проверить подключение, сообщите агенту, что URL установлены. Adapty запросит у App Store тестовое уведомление и дождётся его получения. Если оно не придёт, агент объяснит причину.

Пересылка событий Google Play

Google Play отправляет уведомления в топик Pub/Sub. Adapty подписывается на тот же топик, который уже использует RevenueCat, в качестве второго подписчика — RevenueCat при этом продолжает получать события.

1. Чтобы начать пересылку, спросите у агента:

   Forward Google Play events for my Adapty app "Acme Fitness" to Adapty, and keep RevenueCat receiving them.

2. Чтобы предоставить Adapty доступ к топику, создайте JSON-ключ для сервисного аккаунта, который использует RevenueCat. В Google Cloud Console перейдите в IAM & Admin > Service Accounts, откройте аккаунт — обычно это revenuecat-service-account, затем перейдите в Keys > Add key и выберите JSON. Новый ключ не затронет работу RevenueCat. Подробнее см. в руководстве Google по созданию ключа сервисного аккаунта.

3. Чтобы загрузить ключ, на открытой агентом странице дашборда Adapty загрузите файл в поле Google Play service account key (JSON). Ключ передаётся напрямую в Adapty и никогда не проходит через агент или CLI.

4. Чтобы подписать Adapty на топик, передайте агенту его ID. В RevenueCat откройте настройки вашего приложения Google Play и скопируйте Topic ID из раздела Google developer notifications. Это же значение отображается в Google Play Console в разделе Monetize > Monetization setup > Topic name.

   Adapty подписывается на топик, затем публикует тестовое уведомление и ожидает его получения. Если уведомление не приходит, агент сообщит причину.

5. Если тест завершается ошибкой из-за прав доступа, выдайте сервисному аккаунту роль Pub/Sub Editor в проекте топика либо роль Pub/Sub Subscriber на топике и Pub/Sub Editor в проекте ключа. Затем попросите агента повторить проверку.

Тестирование и выпуск новой версии приложения

Если вы читаете это, значит, вы уже:

• Перенесли каталог в Adapty
• Перенесли дизайны пейволов, если используете флоу
• Заменили RevenueCat SDK на Adapty
• Проработали ADAPTY_SETUP.md вместе с вашим агентом
• Настроили интеграции в Adapty
• Настроили пересылку событий App Store и Google Play в Adapty
• Сделали тестовую покупку в песочнице
• Выпустили новую версию приложения

Если вы отметили все пункты выше — просто совершите тестовую покупку в песочнице, а затем выпускайте приложение.

(Необязательно) Импортируйте историю транзакций

Импорт заполняет профили и графики историей платежей ваших пользователей. Он не влияет на чей-либо доступ.

Два миграционных процесса импортируют историю в приложение, созданное в ходе миграции каталога. Воспользуйтесь Cloud Export, если ваш тарифный план RevenueCat его поддерживает.

С экспортом через RevenueCat Cloud Export

RevenueCat ежедневно отправляет экспорт в бакет, который Adapty подготавливает для вашего приложения, а Adapty импортирует каждый полученный файл.

1. Чтобы начать импорт, обратитесь к агенту:

   Import the RevenueCat transaction history into my Adapty app "Acme Fitness" with a Cloud Export.

2. Чтобы подключить экспорт, передайте агенту External ID из RevenueCat. В RevenueCat откройте настройки Scheduled Data Exports, выберите IAM Role (ARN) в качестве типа учётных данных и скопируйте External ID, который показывает RevenueCat. External ID не является секретным.

3. Чтобы завершить настройку экспорта, введите в RevenueCat bucket, регион и role ARN, которые предоставил агент. Включите Receive new and updated transactions only. Иначе RevenueCat будет каждый день экспортировать всю историю, а Adapty — импортировать каждый файл.

RevenueCat может доставить первый файл с задержкой до 24 часов, а Adapty проверяет наличие новых файлов в бакете каждый час. Миграция завершается автоматически через неделю после того, как Adapty импортирует первый файл. Customer User ID каждого импортированного профиля — rc_last_seen_app_user_id_alias.

Через поддержку

Используйте этот способ, если ваш тарифный план RevenueCat не включает Cloud Export: поддержка RevenueCat отправляет вам экспорт, а поддержка Adapty его импортирует.

1. Чтобы начать импорт, попросите своего агента:

   Import the RevenueCat transaction history into my Adapty app "Acme Fitness" through support.

2. Чтобы запросить экспорт, отправьте в поддержку RevenueCat первое из двух сообщений, которые предложит агент.

3. Чтобы импортировать данные, перешлите файлы, полученные от RevenueCat, в поддержку Adapty вместе со вторым сообщением. Прикрепите файлы точно в том виде, в каком их прислал RevenueCat: открытие, пересохранение или объединение файлов изменит формат столбцов, который ожидает импорт.

Что импортируется

Следующие данные будут импортированы в Adapty для каждой транзакции:

Параметр	Описание
user_id	Customer User ID — основной идентификатор пользователя в Adapty и вашей системе.
apple_original_transaction_id	Для цепочек подписок — это дата покупки исходной транзакции, связанной через store_original_transaction_id.
google_product_id	Идентификатор продукта в Google Play Store.
google_purchase_token	Уникальный идентификатор транзакции, выдаваемый Google Play и необходимый для валидации.
country	Страна пользователя.
created_at	Дата и время создания пользователя.
subscription_expiration_date	Дата и время истечения подписки.
email	Электронная почта конечного пользователя.
phone_number	Номер телефона конечного пользователя.
idfa	Identifier for Advertisers (IDFA) — идентификатор, присваиваемый Apple устройству пользователя.
idfv	Identifier for Vendors (IDFV) — код, присваиваемый всем приложениям одного разработчика и общий для этих приложений на устройстве.
advertising_id	Уникальный идентификатор, предоставляемый ОС Android для отслеживания рекламодателями.
attribution_channel	Название маркетингового канала.
attribution_campaign	Название маркетинговой кампании.
attribution_ad_group	Группа объявлений атрибуции.
attribution_ad_set	Набор объявлений атрибуции.
attribution_creative	Ключевое слово креатива атрибуции.

В дополнение к этому будут импортированы идентификаторы интеграций для следующих интеграций: Amplitude, Mixpanel, AppsFlyer, Adjust и FacebookAds.

Что остаётся за кадром

• Каждая транзакция повторно проверяется в сторе при импорте, поэтому строки, которые стор больше не распознаёт, отбрасываются.
• Строки без реального идентификатора транзакции стора — например, промо-права или права, выданные вручную в RevenueCat, — импортируются как профили без транзакций. Чтобы восстановить доступ таким пользователям, выдайте им уровень доступа через серверный API.
• История возвратов и проблем с оплатой не переносится в исходном виде: у возврата сохраняется только дата отмены, а состояние проблемы с оплатой по подписке фиксируется на момент импорта, а не с историческими датами.

FAQ

Я успешно установил Adapty SDK и выпустил новую версию приложения. Что произойдёт с моими действующими подписчиками, которые не обновили приложение до версии с Adapty SDK?

Большинство пользователей заряжают телефоны на ночь — именно тогда App Store обычно автоматически обновляет все приложения, так что это не должно стать проблемой. Небольшое количество платных подписчиков всё же может не обновиться, но они по-прежнему сохранят доступ к премиум-контенту. Беспокоиться об этом не нужно, и принудительно заставлять их обновляться тоже.

Нужно ли мне как можно быстрее экспортировать исторические данные из RevenueCat, или я их потеряю?

Торопиться не нужно — сначала выпустите релиз с SDK Adapty, а уже потом импортируйте историю. Мы восстановим историю платежей ваших пользователей и заполним профили и графики.

Я использую MMP (AppsFlyer, Adjust и т. д.) и аналитику (Mixpanel, Amplitude и т. д.). Как убедиться, что всё будет работать?

Сначала нужно передать нам идентификаторы сторонних сервисов через SDK, чтобы мы могли отправлять туда данные. Прочитайте гайд по интеграции атрибуции и по интеграции аналитики. Для исторических данных и старых пользователей обязательно передайте нам эти идентификаторы из данных, экспортированных из RevenueCat.