Начальная интеграция с Paddle

Adapty поддерживает сценарии web2app, отслеживая веб-платежи и подписки, оформленные через Paddle.

Интеграция охватывает покупки, инициированные на веб-сайте, и синхронизирует их с доступом в мобильном приложении и аналитикой наряду со встроенными покупками из сторов. Это полезно в следующих сценариях:

  • Собирать данные о подписках из встроенных покупок и покупок на сайте в единой системе
  • Предоставлять доступ к платным функциям мобильного приложения пользователям, которые оформили покупку на сайте
  • Просматривать аналитику и данные о подписках из всех каналов продаж в одном дашборде

Apple теперь разрешает приложениям в US App Store размещать ссылки на внешние платёжные системы, однако приложения всё ещё могут быть обязаны предлагать встроенные покупки наряду с внешними вариантами. Ознакомьтесь с актуальными правилами App Store для своего региона и категории приложения.

Эта интеграция предназначена для отслеживания и синхронизации веб-покупок в Paddle. Если вам нужно перенаправить пользователей из приложения на веб-страницу оформления заказа, используйте веб-пейволы Adapty.

Чтобы настроить интеграцию с Paddle, выполните следующие шаги:

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

Интеграция использует вебхуки для отправки данных о подписках из Paddle в Adapty. Чтобы связать аккаунты Adapty и Paddle, вам нужно:

  1. Предоставить API-ключи Paddle.
  2. Добавить URL вебхука Adapty в Paddle.

Шаги ниже применимы как к Production, так и к Test-окружению. Вы можете настроить оба одновременно. Указанные ссылки ведут на Production-окружение — чтобы получить ссылки для Test-окружения, просто добавьте sandbox- в начало каждого URL. Например, используйте https://sandbox-vendors.paddle.com/authentication-v2 вместо https://vendors.paddle.com/authentication-v2.

1.1. Получите и добавьте API-ключи Paddle

  1. В Paddle перейдите в Developer Tools → Authentication и нажмите New API key.
paddle-new-key.webp
  1. Введите название ключа и установите срок его действия. Чтобы API-ключ работал с Adapty, необходимо предоставить ему разрешение Read для всех сущностей. Нажмите Save.
paddle-key.webp
  1. Нажмите Copy key.
copy-paddle-key.webp
  1. В дашборде Adapty перейдите в App Settings → Paddle и вставьте ключ в поле Paddle API key.

Если вы задали срок действия для Paddle API key, вам нужно вручную сгенерировать новый ключ и обновить его в Adapty до истечения срока. Когда ключ истечёт, интеграция прекратит работу без каких-либо предупреждений, и пользователи не смогут совершать покупки.

paddle-api-keys-adapty.webp

1.2. Добавьте события, которые будут отправляться в Adapty

  1. Скопируйте Webhook URL с той же страницы Paddle в Adapty.
  2. В Paddle перейдите в Developer Tools → Notifications и нажмите New destination, чтобы добавить вебхук.
paddle-webhook.webp

  1. Введите понятное название для вебхука. Рекомендуем включить в него «Adapty», чтобы легко найти его при необходимости.

  2. Вставьте Webhook URL из Adapty в поле URL. Убедитесь, что используете вебхук для нужного окружения.

  3. Установите Notification type в значение Webhook.

paddle-create-webhook.webp
  1. Выберите следующие события:

  • subscription.created

    • subscription.updated

    • transaction.created

    • transaction.updated

    • adjustment.created

    • adjustment.updated

paddle_events.png
  1. Нажмите Save destination, чтобы завершить настройку вебхука.

1.3. Получите и добавьте секретный ключ webhook

  1. В окне Notifications нажмите на три точки рядом с только что созданным webhook и выберите Edit destination.
  2. В панели Edit destination появится новое поле Secret key. Скопируйте его.
paddle-webhook-secret-key-copy.webp
  1. В Adapty перейдите в App Settings → Paddle и вставьте ключ в поле Notification secret key. Этот ключ используется для проверки данных вебхука в Adapty.
paddle-webhook-secret-key.webp

1.4. Сопоставление клиентов Paddle с профилями Adapty

Adapty должен связать каждую покупку с профилем клиента, чтобы её можно было использовать в вашем приложении. По умолчанию профили создаются автоматически, когда Adapty получает вебхуки от Paddle. Вы можете выбрать, какое значение использовать в качестве customer_user_id в Adapty:

  1. По умолчанию и рекомендуется: customer_user_id, который вы передаёте в поле custom_data (см. документацию Paddle)
  2. email из объекта Paddle Customer (см. документацию Paddle)
  3. Paddle Customer ID в формате ctm-... (см. документацию Paddle)
  4. Не создавать профили. Выберите этот вариант, если хотите самостоятельно управлять профилями пользователей. Вы можете настроить, какое значение использовать, в поле Profile creation behavior в App Settings → Paddle.
paddle-users.webp

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

Обязательно добавьте ваши продукты Paddle в дашборд Adapty или добавьте Paddle product ID к уже существующим продуктам. Adapty отслеживает события только для транзакций, связанных с этими продуктами. Если пропустить этот шаг, события транзакций создаваться не будут.

Paddle работает в Adapty так же, как App Store и Google Play — это ещё одна платформа для продажи цифровых продуктов. Чтобы настроить её, добавьте нужные значения product_id и price_id из Paddle в разделе Products в Adapty.

paddle-create-product.webp

В Paddle идентификаторы продуктов выглядят как pro_..., а идентификаторы цен — как pri_.... Их можно найти в каталоге продуктов Paddle, открыв конкретный продукт:

paddle-product-price.webp

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

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

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

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

После завершения настройки можно протестировать интеграцию. Транзакции в Test-окружении Paddle будут отображаться в Adapty со статусом Test, а транзакции из Production — со статусом Production.

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

Важные замечания

  • В аналитике Adapty суммы транзакций включают налоги и комиссии Paddle, что отличается от дашборда Paddle, где суммы отображаются после вычета налогов и комиссий. Поэтому числа в Adapty будут выше, чем в вашем дашборде Paddle.
  • В отличие от других сторов, возвраты в Paddle затрагивают только конкретную транзакцию и не отменяют подписку автоматически. Подписка остаётся активной, если её не отменить явно.
  • Вы также можете передавать variation_id в поле custom_data, чтобы атрибутировать покупки конкретным экземплярам пейвола. Adapty обработает эти данные из вебхуков и учтёт их в аналитике.

При работе с платными триалами в Paddle нужно создать два продукта в Adapty:

  1. Создайте разовую покупку и свяжите её с ценой Paddle, которая списывает оплату за триальный период.
  2. Затем создайте продукт-подписку (Monthly/Weekly/и т. д.) и свяжите его с ценой Paddle, в которой настроен бесплатный триал.

С точки зрения Paddle, это один продукт с двумя ценами в рамках одной транзакции: одна цена — за триальный период (например, $0.99), другая — за бесплатный триал ($0.00). С точки зрения Adapty это создаёт два отдельных события: разовая покупка для пробного платежа и событие начала пробного периода для продукта-подписки.

Например, когда пользователь начинает платный пробный период за $0,99 для подписки за $9,99/месяц, Paddle создаёт одну транзакцию с обеими ценами, тогда как Adapty обрабатывает это как разовую покупку на $0,99 (немедленный платёж) и событие начала пробного периода на $0,00 (будущая подписка за $9,99/месяц).

Когда пользователи отменяют платный пробный период, вы получаете события Trial expired и Trial renewal canceled.

Больше возможностей с данными Paddle

Чтобы события Paddle работали с интеграциями, ваши пользователи должны хотя бы раз войти в приложение через аккаунт App Store/Google Play.

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

Интеграции для передачи и анализа событий Paddle:

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

  • Отмены: Paddle предлагает два варианта отмены подписки:

    1. Немедленная отмена: подписка отменяется сразу.

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

  • Возвраты: Adapty отслеживает полные и частичные возвраты средств.

  • Grace period: По умолчанию Paddle применяет фиксированный льготный период в 30 дней при проблемах с оплатой, в течение которого подписка остаётся активной. Вы можете настроить продолжительность льготного периода и действие по его окончании (приостановка или отмена подписки). Пробные периоды: если оплата не проходит после окончания пробного периода, статус подписки меняется на past_due. В production Paddle’s Retain применяет окно повторных попыток оплаты (dunning window), чтобы попытаться восстановить платёж до того, как подписка будет отменена или приостановлена. В песочнице Retain недоступен, поэтому повторные попытки оплаты не предпринимаются, и подписка остаётся в статусе past_due бессрочно.

См. также: