Adapty поддерживает web2app-сценарии, отслеживая веб-платежи и подписки, оформленные через Stripe. Эта интеграция охватывает покупки, совершённые через веб (Stripe Checkout, размещённые платёжные страницы или пользовательские веб-флоу), и синхронизирует их с доступом в мобильном приложении и аналитикой.

Она полезна в следующих случаях:

• Автоматически предоставлять доступ к платным функциям пользователям, которые купили подписку через веб, а позже установили приложение и вошли в свой аккаунт
• Хранить всю аналитику подписок в едином дашборде Adapty (включая когорты, прогнозы и остальные инструменты аналитики) Несмотря на то что веб-покупки становятся всё популярнее среди приложений, Apple App Store разрешает систему, отличную от встроенных покупок для цифровых товаров, только в США. Убедитесь, что вы не продвигаете веб-подписки внутри приложения для пользователей из других стран — иначе приложение может быть отклонено или заблокировано.

Шаги ниже описывают, как настроить интеграцию со Stripe.

1. Подключите Stripe к Adapty

Эта интеграция основана на том, что Adapty получает данные о подписках из Stripe через вебхук. Поэтому нужно связать аккаунт Adapty с аккаунтом Stripe: указать API-ключи и настроить URL вебхука Adapty в Stripe. Чтобы автоматически настроить вебхук, установите приложение Adapty в Stripe:

0. Определите, будете ли вы подключать Stripe в тестовом режиме или в рабочем. Если вы сначала делаете это в тестовом режиме, шаги ниже нужно будет повторить и для рабочего режима.

1. Перейдите в Stripe App Marketplace и установите приложение Adapty. Обратите внимание, что режим песочницы не поддерживает установку приложений — это можно сделать только в рабочем или тестовом режиме.

2. Предоставьте приложению необходимые разрешения. Это позволит Adapty получить доступ к данным и истории подписок. Затем нажмите Continue to app settings, чтобы продолжить.

В нижней части всплывающего окна с разрешениями можно выбрать режим установки приложения: live или test.

3. В появившемся окне сгенерируйте новый ограниченный ключ. Для этого потребуется подтвердить личность с помощью электронной почты, Touch ID или ключа безопасности. После генерации ключа вы больше не сможете его увидеть, поэтому сохраните его в надёжном месте — менеджере паролей или хранилище секретов.

4. Скопируйте сгенерированный ключ из всплывающего окна и перейдите в App Settings → Stripe в Adapty. Вставьте ключ в раздел Stripe App Restricted API Key в соответствии с вашим режимом. Обратите внимание, что для тестового и боевого режимов нужно генерировать разные ключи.

Всё готово! Теперь создайте продукты в Stripe и добавьте их в Adapty.

Устаревший способ установки

1. Перейдите в раздел Developers → API Keys в Stripe:

2. Нажмите кнопку Reveal live (test) key button рядом с заголовком Secret key, скопируйте ключ и перейдите в App Settings → Stripe в Adapty. Вставьте ключ в соответствующее поле:
3. Затем скопируйте Webhook URL внизу той же страницы в Adapty. Перейдите в Developers → Webhooks в Stripe и нажмите кнопку Add endpoint:
4. Вставьте URL вебхука из Adapty в поле Endpoint URL. Затем выберите Latest API version в поле Version для вебхука. Затем отметьте следующие события:

• charge.refunded
  • customer.subscription.created
  • customer.subscription.deleted
  • customer.subscription.paused
  • customer.subscription.resumed
  • customer.subscription.updated
  • invoice.created
  • invoice.updated
  • payment_intent.succeeded

5. Нажмите «Add endpoint», затем нажмите «Reveal» под полем «Signing secret». Это ключ, который используется для расшифровки данных вебхука на стороне Adapty — скопируйте его после открытия:

6. Вставьте этот ключ в App Settings → Stripe в поле «Stripe Webhook Secret»:

2. Создайте продукты в Stripe

Перейдите в каталог продуктов Stripe и создайте продукты, которые хотите продавать, а также их тарифные планы. Обратите внимание, что Stripe позволяет создавать несколько тарифных планов для одного продукта — это удобно для гибкой настройки предложения без необходимости создавать дополнительные продукты.

3. Добавьте продукты Stripe в Adapty

Мы работаем со Stripe так же, как с App Store и Google Play: это просто ещё один стор, в котором вы продаёте свои цифровые продукты. Настройка выполняется аналогично: просто добавьте продукты Stripe (а именно их product_id и price_id) в раздел Products в Adapty:

ID продуктов в Stripe выглядят как prod_..., а ID цен — как price_.... Их легко найти для каждого продукта в каталоге продуктов Stripe, открыв любой продукт: После того как вы добавили все необходимые продукты, следующий шаг — сообщить Stripe, какой пользователь совершает покупку, чтобы Adapty мог её отследить!

4. Обогащайте покупки на сайте идентификатором пользователя

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

Чтобы уровни доступа были согласованными на всех платформах (веб или мобильные), необходимо использовать единый идентификатор пользователя, по которому Adapty сможет распознать его из вебхуков. Это может быть email, номер телефона или любой другой ID из вашей системы авторизации. Определите, какой идентификатор вы хотите использовать для идентификации пользователей. Затем найдите в коде место, где инициализируется оплата через Stripe, и добавьте этот идентификатор пользователя в объект metadata объекта Stripe Subscription (sub_...) или Checkout Session (ses_...) как customer_user_id:

{'customer_user_id': "YOUR_USER_ID"}

Это единственное дополнение, которое нужно внести в ваш код. После этого Adapty будет разбирать все вебхуки, получаемые от Stripe, извлекать эти metadata и корректно связывать подписки с вашими пользователями.

5. Предоставьте доступ пользователям в мобильном приложении

Чтобы пользователи мобильного приложения, пришедшие с веба, могли получить доступ к платным функциям, просто вызовите Adapty.activate() или Adapty.identify() с тем же customer_user_id, который вы передали на предыдущем шаге (подробнее см. Идентификация пользователей iOS, Android, React Native, Flutter и Unity ).

6. Протестируйте интеграцию

Убедитесь, что вы выполнили шаги выше как для Sandbox, так и для Production. Транзакции, совершённые в Test mode Stripe, будут считаться Sandbox в Adapty.

Поведение при создании профиля

Adapty должен привязать покупку к профилю пользователя, чтобы она стала доступна на мобильном устройстве — поэтому по умолчанию профили создаются при получении вебхуков от Stripe. Вы можете выбрать, что использовать в качестве customer user ID в Adapty:

1. По умолчанию и рекомендуется: customer_user_id, указанный в метаданных на шаге 4 выше
2. email в объекте Customer в Stripe (см. документацию Stripe)
3. client_reference_id в объекте Session в Stripe (см. документацию Stripe)

Выбрать нужный идентификатор можно в разделе App Settings → Stripe.

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

Текущие ограничения

Апгрейд, даунгрейд и пропорциональное распределение

Изменения подписки — апгрейд или даунгрейд — могут приводить к пропорциональным списаниям. Adapty не учитывает эти списания в расчёте выручки. Лучше отключить эти опции вручную через дашборд Stripe. Также это можно сделать, установив атрибут proration_behaviour в значение none через Stripe API.

Отмены

В Stripe есть два варианта отмены подписки:

1. Немедленная отмена: подписка отменяется сразу с опцией пропорционального распределения или без неё
2. Отмена в конце периода: подписка отменяется по истечении текущего расчётного периода (аналогично встроенным подпискам в магазинах приложений)

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

Проблемы с оплатой и льготный период

Когда у пользователя возникают проблемы с оплатой, Adapty генерирует событие billing issue и отзывает доступ. Льготный период Stripe пока не поддерживается — это будет реализовано в будущих релизах.

Возвраты

Adapty отслеживает только полные возвраты. Частичные возвраты и возвраты с пропорциональным распределением в настоящее время не поддерживаются.

Уникальность идентификатора транзакции

Adapty сопоставляет профили и транзакции по store_transaction_id и store_original_transaction_id. Эти значения должны быть уникальными в средах Test и Production.

Почему это важно

Если один и тот же идентификатор транзакции существует в обеих средах, Adapty воспринимает их как одну транзакцию, что приводит к следующим последствиям:

• Продакшен-покупки наследуют уровни доступа и идентификаторы продуктов из тестовой среды
• Неверные идентификаторы продуктов и сведения о среде в ответах API
• Нарушение связи профилей и событий подписки

Как обеспечить уникальность

Stripe invoice IDs can overlap between Test and Live environments. To prevent cross-environment collisions, choose one approach

Option 1: Account-level numbering with environment prefixes

Configure prefixes separately for each environment:

1. В Stripe Dashboard переключитесь в тестовый режим.
2. Перейдите в Settings → Billing → Invoices.
3. Установите Invoice numbering в значение Sequentially across your account.
4. Установите Invoice prefix в значение TEST- (или другой префикс, который будет уникальным для тестового окружения).
5. Переключитесь в рабочий режим и повторите шаги 2–4, используя LIVE- (или другой префикс, уникальный для рабочего окружения) в качестве префикса.

Вариант 2: нумерация на уровне клиента

Установите Invoice numbering в Stripe settings -> Billing -> Invoices tab в значение Sequentially for each customer (customer-level).

Даже при такой настройке, если вы удалите счёт, Stripe может повторно использовать этот ID для новых счетов того же клиента. Поэтому по возможности избегайте удаления счетов.

Получите больше от данных Stripe

После интеграции со Stripe Adapty сразу готова предоставлять аналитику. Чтобы использовать данные Stripe по максимуму, настройте дополнительные интеграции Adapty для передачи событий Stripe — так вся аналитика подписок окажется в едином дашборде Adapty.

Обратите внимание, что variation_id считывается из метаданных только в объектах Stripe Subscription (sub_...) и Checkout Session (ses_...):

{
  'customer_user_id': "YOUR_USER_ID",
  'variation_id': "YOUR_VARIATION_ID"
}

:::

Интеграции, которые можно использовать для передачи и анализа событий Stripe:

• Amplitude
• Webhook
• Firebase
• Mixpanel
• Posthog

Поддерживаемые события Stripe

Adapty поддерживает следующие события Stripe:

• charge.refunded
• customer.subscription.created
• customer.subscription.deleted
• customer.subscription.paused
• customer.subscription.resumed
• customer.subscription.updated
• invoice.created
• invoice.updated
• payment_intent.succeeded