Получение кастомных пейволов и продуктов в iOS SDK
Прежде чем отображать кастомные пейволы, необходимо получить информацию о них. Обратите внимание, что данный раздел посвящён кастомным пейволам. Если вы используете флоу или пейволы, созданные в Flow & Paywall Builder или old Paywall Builder, обратитесь к гайдам по получению флоу и пейволов в приложении iOS, Android, React Native, Flutter, и Unity .
Хотите увидеть реальный пример интеграции Adapty SDK в мобильное приложение? Посмотрите наши примеры приложений, которые демонстрируют полную настройку, включая отображение пейволов, совершение покупок и другую базовую функциональность.
Прежде чем начать получать флоу и продукты в мобильном приложении (нажмите, чтобы развернуть)
-
Создайте продукты в дашборде Adapty.
-
Создайте флоу или пейвол и добавьте в него продукты в дашборде Adapty.
-
Создайте плейсменты и добавьте флоу или пейвол в плейсмент в дашборде Adapty.
-
Установите Adapty SDK в мобильном приложении.
Получение информации о флоу
В Adapty продукт объединяет в себе продукты из App Store и Google Play. Эти кросс-платформенные продукты интегрируются во флоу и пейволы, позволяя демонстрировать их в конкретных плейсментах мобильного приложения.
Чтобы отобразить продукты, необходимо получить AdaptyFlow из одного из ваших плейсментов с помощью метода getFlow.
Не хардкодьте идентификаторы продуктов. Единственный ID, который нужно хардкодить, — это ID плейсмента. Флоу настраиваются удалённо, поэтому количество продуктов и доступных офферов может меняться в любой момент. Ваше приложение должно обрабатывать эти изменения динамически — если сегодня флоу возвращает два продукта, а завтра три, отображайте все из них без изменений в коде.
| Параметр | Наличие | Описание |
|---|---|---|
| placementId | обязательный | Идентификатор плейсмента. Это значение вы указывали при создании плейсмента в дашборде Adapty. |
| fetchPolicy | по умолчанию: .reloadRevalidatingCacheData |
Однако если у ваших пользователей нестабильное интернет-соединение, рассмотрите Третья политика, Обратите внимание, что кэш сохраняется при перезапуске приложения и очищается только при его переустановке или вручную. Adapty SDK хранит флоу и пейволы в двух слоях: регулярно обновляемый кэш, описанный выше, и резервные пейволы. Также для ускорения загрузки флоу и пейволов используется CDN, а на случай его недоступности — отдельный резервный сервер. |
| loadTimeout | по умолчанию: 5 сек | Это значение ограничивает таймаут данного метода. Если сервер Adapty не отвечает вовремя или возвращает ошибку, SDK возвращает кэшированный флоу. Если кэша нет, а сервер не ответил или вернул ошибку, SDK запрашивает флоу с резервного сервера (CDN-копия, которая обслуживает только аудиторию All Users данного плейсмента). В крайнем случае SDK возвращает флоу из вашего резервного файла. Обратите внимание, что в редких случаях метод может завершиться чуть позже указанного в |
В v4 параметр locale перенесён из getFlow в getFlowConfiguration (используется только при рендеринге через AdaptyUI). Для кастомных пейволов все доступные локали возвращаются вместе в flow.remoteConfigs — выберите ту, которая соответствует языку устройства пользователя или настройкам вашего приложения.
Чтобы заполнить кэш до того, как пользователь откроет флоу, вызовите preloadFlows (iOS SDK 4.1+) для нескольких плейсментов сразу. Передайте fetchPolicy: .returnCacheDataElseLoad, чтобы читать заранее загруженную копию из кэша, не обращаясь к сети.
Не прописывайте ID продуктов в коде! Поскольку флоу настраиваются удалённо, доступные продукты, их количество и специальные предложения (например, бесплатные пробные периоды) могут меняться со временем. Убедитесь, что ваш код корректно обрабатывает подобные сценарии. Например, если изначально вы получаете 2 продукта, приложение должно отображать именно 2 продукта. Но если впоследствии вы получите 3 продукта, приложение должно показать все 3 без каких-либо изменений в коде. Единственное, что нужно прописать в коде — это ID плейсмента.
Параметры ответа:
| Параметр | Описание |
|---|---|
| Flow | Объект AdaptyFlow, содержащий плейсмент, идентификаторы (id, variationId), название варианта (variationName, опционально, SDK 4.2+), название, варианты пейвола (paywalls), массив remoteConfigs (по одной записи на каждую настроенную локаль) и флаг hasViewConfiguration. Чтобы получить продукты для флоу, вызовите getPaywallProducts(flow:). |
Получение продуктов
После получения флоу вы можете запросить массив продуктов, соответствующий ему:
Параметры ответа:
| Параметр | Описание |
|---|---|
| Products | Список объектов AdaptyPaywallProduct с идентификатором продукта, его названием, ценой, валютой, длительностью подписки и рядом других свойств. |
При реализации собственного дизайна пейвола вам, скорее всего, понадобятся свойства объекта AdaptyPaywallProduct. Ниже показаны наиболее часто используемые свойства, однако полный список доступных свойств приведён в документации по ссылке.
| Свойство | Описание |
|---|---|
| Title | Для отображения названия продукта используйте product.localizedTitle. Обратите внимание: локализация основана на стране стора, выбранной пользователем, а не на локали устройства. |
| Price | Для отображения локализованной цены используйте product.localizedPrice. Локализация основана на локали устройства. Также можно получить цену в виде числа через product.price — значение будет указано в местной валюте. Для получения символа валюты используйте product.currencySymbol. |
| Subscription Period | Для отображения периода (например, неделя, месяц, год и т. д.) используйте product.localizedSubscriptionPeriod. Локализация основана на локали устройства. Для программного получения периода подписки используйте product.subscriptionPeriod. Через это свойство доступен enum unit, возвращающий единицу длительности (day, week, month, year или unknown). Значение numberOfUnits возвращает количество единиц периода. Например, для квартальной подписки в свойстве unit будет .month, а в numberOfUnits — 3. |
| Billing plan | Для продукта с годовым обязательством используйте product.subscriptionPricingTerms, чтобы отобразить обе цены, которые требует Apple: localizedBillingPrice и localizedBillingPeriod — для ежемесячного платежа, commitmentInfo.localizedPrice и commitmentInfo.localizedPeriod — для годовой суммы. billingPlan равен .monthly для тарифа с обязательством и .upFront в остальных случаях. Для тарифа с обязательством product.price, product.localizedPrice и product.subscriptionPeriod возвращают годовую сумму и период, а не размер отдельного платежа. Требуется Adapty SDK 4.3 или новее. localizedBillingPeriod и commitmentInfo.localizedPeriod требуют Adapty SDK 4.4 или новее. При использовании более ранней версии SDK форматируйте billingPeriod в приложении самостоятельно и отображайте годовой период из product.localizedSubscriptionPeriod. |
| Introductory Offer | Чтобы показать бейдж или другой индикатор наличия introductory offer у подписки, используйте свойство product.subscriptionOffer. Этот объект содержит следующие полезные свойства:• offerType: тип офера с предопределёнными значениями introductory, promotional и winBack (начиная с SDK 4.1 — открытая структура, а не enum, поэтому оператор switch по нему требует ветки default). Бесплатные пробные периоды и начальные скидочные подписки имеют тип introductory.• price: скидочная цена в виде числа. Для бесплатных пробных периодов здесь будет 0.• localizedPrice: отформатированная цена скидки для локали пользователя.• localizedNumberOfPeriods: строка, локализованная согласно локали устройства, описывающая длительность офера. Например, для трёхдневного пробного периода в этом поле будет 3 days.• subscriptionPeriod: также можно получить отдельные детали периода офера через это свойство — оно работает так же, как описано в предыдущем разделе.• localizedSubscriptionPeriod: отформатированный период подписки скидки для локали пользователя. |
В v4 все продукты, возвращаемые методом getPaywallProducts(flow:), уже содержат информацию о подходящих офферах. Отдельный вызов getPaywallProductsWithoutDeterminingOffer из v3 был удалён.
Ускорьте загрузку флоу с помощью флоу для аудитории по умолчанию
Как правило, флоу загружаются практически мгновенно, поэтому беспокоиться об ускорении этого процесса не нужно. Однако если у вас много аудиторий и плейсментов, а у ваших пользователей слабое интернет-соединение, загрузка флоу может занять больше времени, чем хотелось бы. В таких ситуациях имеет смысл показывать флоу по умолчанию — это обеспечит плавный пользовательский опыт вместо пустого экрана.
Чтобы решить эту задачу, можно использовать метод getFlowForDefaultAudience, который получает флоу указанного плейсмента для аудитории All Users. Однако важно понимать, что рекомендуемый подход — получать флоу через метод getFlow, как описано в разделе Получение информации о флоу выше.
Почему мы рекомендуем использовать getFlow
Метод getFlowForDefaultAudience имеет ряд существенных недостатков:
- Возможные проблемы с обратной совместимостью: если вам нужно показывать разные флоу для разных версий приложения (текущей и будущих), могут возникнуть сложности. Придётся либо проектировать флоу с поддержкой текущей (устаревшей) версии, либо мириться с тем, что пользователи на этой версии могут столкнуться с нерендерящимися флоу.
- Потеря таргетинга: все пользователи будут видеть один и тот же флоу, настроенный для аудитории All Users, — а значит, вы теряете персонализированный таргетинг (в том числе по странам, маркетинговой атрибуции или собственным кастомным атрибутам).
Если вас устраивают эти недостатки ради более быстрой загрузки флоу, используйте метод getFlowForDefaultAudience следующим образом. В противном случае придерживайтесь метода getFlow, описанного выше.
| Параметр | Наличие | Описание |
|---|---|---|
| placementId | обязательный | Идентификатор плейсмента. Это значение вы указали при создании плейсмента в дашборде Adapty. |
| fetchPolicy | по умолчанию: .reloadRevalidatingCacheData |
Однако если у ваших пользователей нестабильное интернет-соединение, рассмотрите Третья политика, Обратите внимание, что кэш сохраняется при перезапуске приложения и очищается только при его переустановке или вручную. |
Прежде чем отображать кастомные пейволы, нужно получить информацию о них. Обратите внимание, что этот раздел относится к кастомным пейволам. Руководство по получению пейволов, созданных с помощью Paywall Builder, см. в гайды по получению пейволов Paywall Builder в вашем приложении iOS, Android, React Native, Flutter и Unity .
Хотите увидеть реальный пример интеграции Adapty SDK в мобильное приложение? Посмотрите наши примеры приложений, которые демонстрируют полную настройку, включая отображение пейволов, совершение покупок и другую базовую функциональность.
Прежде чем начать получать пейволы и продукты в мобильном приложении (нажмите, чтобы развернуть)
-
Создайте продукты в дашборде Adapty.
-
Создайте пейвол и добавьте в него продукты в дашборде Adapty.
-
Создайте плейсменты и добавьте пейвол в плейсмент в дашборде Adapty.
-
Установите Adapty SDK в мобильном приложении.
Получение информации о пейволе
В Adapty продукт объединяет продукты из App Store и Google Play. Эти кросс-платформенные продукты добавляются в пейволы, что позволяет показывать их в нужных плейсментах мобильного приложения.
Чтобы отобразить продукты, нужно получить пейвол из одного из ваших плейсментов с помощью метода getPaywall.
Не хардкодьте ID продуктов. Единственный ID, который можно захардкодить — это ID плейсмента. Пейволы настраиваются удалённо, поэтому количество продуктов и доступных офферов может меняться в любой момент. Приложение должно обрабатывать эти изменения динамически — если сегодня пейвол возвращает два продукта, а завтра три, отображайте все без изменений в коде.
| Параметр | Наличие | Описание |
|---|---|---|
| placementId | обязательный | Идентификатор плейсмента. Это значение вы указали при создании плейсмента в дашборде Adapty. |
| locale | необязательный по умолчанию: | Идентификатор локализации пейвола. Ожидается, что этот параметр будет языковым кодом, состоящим из одного или нескольких подтегов, разделённых символом минуса (-). Первый подтег обозначает язык, второй — регион. Пример: Подробнее о кодах локалей и рекомендациях по их использованию см. в разделе Локализации и коды локалей. |
| fetchPolicy | по умолчанию: .reloadRevalidatingCacheData |
Однако если вы считаете, что у ваших пользователей нестабильное интернет-соединение, рассмотрите Третья политика, Обратите внимание, что кэш сохраняется при перезапуске приложения и очищается только при переустановке или ручной очистке. Adapty SDK хранит пейволы в двух слоях: регулярно обновляемый кэш, описанный выше, и резервные пейволы. Мы также используем CDN для ускорения загрузки пейволов и отдельный резервный сервер на случай недоступности CDN. Эта система обеспечивает получение актуальной версии пейволов и надёжность даже при плохом интернет-соединении. |
| loadTimeout | по умолчанию: 5 сек | Это значение ограничивает таймаут для данного метода. Если сервер Adapty не отвечает вовремя или возвращает ошибку, SDK возвращает пейвол с резервного сервера (копия CDN, обслуживающая только аудиторию All Users плейсмента), из кэша или из вашего резервного файла. Обратите внимание, что в редких случаях метод может завершиться по таймауту чуть позже, чем указано в |
Не задавайте product ID в коде! Поскольку пейволы настраиваются удалённо, доступные продукты, их количество и специальные предложения (например, бесплатные пробные периоды) могут меняться со временем. Убедитесь, что ваш код учитывает эти сценарии.
Например, если изначально вы получаете 2 продукта, приложение должно отображать именно 2 продукта. Но если позже вы получите 3 продукта, приложение должно показать все 3 без каких-либо изменений в коде. Единственное, что нужно задать в коде, — это ID плейсмента.
Параметры ответа:
| Параметр | Описание |
|---|---|
| Paywall | Объект AdaptyPaywall с: списком ID продуктов, идентификатором пейвола, Remote Config и другими свойствами. |
Получить продукты
Когда у вас есть пейвол, вы можете запросить массив продуктов, соответствующих ему:
Параметры ответа:
| Параметр | Описание |
|---|---|
| Products | Список объектов AdaptyPaywallProduct с: идентификатором продукта, названием продукта, ценой, валютой, длительностью подписки и рядом других свойств. |
Реализуя собственный дизайн пейвола, вам, скорее всего, понадобятся свойства объекта AdaptyPaywallProduct. Ниже приведены наиболее часто используемые из них — полный список доступных свойств смотрите в связанной документации.
| Свойство | Описание |
|---|---|
| Title | Чтобы отобразить название продукта, используйте product.localizedTitle. Обратите внимание, что локализация основана на стране стора, выбранной пользователем, а не на локали устройства. |
| Price | Чтобы отобразить локализованную цену, используйте product.localizedPrice. Локализация основана на локали устройства. Также можно получить цену в числовом виде через product.price — значение будет в местной валюте. Для получения символа валюты используйте product.currencySymbol. |
| Subscription Period | Чтобы отобразить период (например, неделя, месяц, год и т. д.), используйте product.localizedSubscriptionPeriod. Локализация основана на локали устройства. Для программного получения периода подписки используйте product.subscriptionPeriod. Через это свойство доступен enum unit, который возвращает единицу периода (день, неделя, месяц, год или unknown). Значение numberOfUnits содержит количество единиц периода. Например, для квартальной подписки в свойстве unit будет .month, а в numberOfUnits — 3. |
| Introductory Offer | Чтобы отобразить значок или другой индикатор наличия introductory offer, проверьте свойство product.subscriptionOffer. Этот объект содержит следующие полезные свойства:• offerType: тип оффера с предопределёнными значениями introductory, promotional и winBack (начиная с SDK 4.1 — это открытая структура, а не enum, поэтому switch по нему требует ветки default). Бесплатные пробные периоды и начальные скидочные подписки относятся к типу introductory.• price: скидочная цена в числовом виде. Для бесплатных пробных периодов здесь будет 0.• localizedPrice: отформатированная цена скидки для локали пользователя.• localizedNumberOfPeriods: строка, локализованная по локали устройства и описывающая длительность оффера. Например, для трёхдневного пробного периода в этом поле будет 3 days.• subscriptionPeriod: альтернативный способ получить детали периода оффера — работает так же, как описано в предыдущем разделе.• localizedSubscriptionPeriod: отформатированный период подписки скидки для локали пользователя. |
Проверка доступности introductory offer на iOS
По умолчанию метод getPaywallProducts проверяет доступность introductory offer, promotional offer и win-back offer. Если нужно показать продукты до того, как SDK определит доступность офферов, используйте вместо него метод getPaywallProductsWithoutDeterminingOffer.
После показа первоначальных продуктов обязательно вызовите стандартный метод getPaywallProducts, чтобы обновить продукты с актуальной информацией о доступности офферов.
Ускорьте загрузку пейвола с помощью пейвола для аудитории по умолчанию
Как правило, пейволы загружаются почти мгновенно, поэтому беспокоиться об ускорении этого процесса не нужно. Однако если у вас много аудиторий и пейволов, а пользователь работает с нестабильным интернетом, загрузка пейвола может занять дольше, чем хотелось бы. В таких случаях имеет смысл показывать пейвол по умолчанию — это обеспечит плавный пользовательский опыт вместо ситуации, когда пейвол вообще не отображается.
Чтобы решить эту задачу, можно использовать метод getPaywallForDefaultAudience, который загружает пейвол указанного плейсмента для аудитории All Users. Однако важно понимать, что рекомендуемый подход — загружать пейвол с помощью метода getPaywall, как описано в разделе Получение информации о пейволе выше.
Почему мы рекомендуем использовать getPaywall
Метод getPaywallForDefaultAudience имеет ряд существенных недостатков:
- Потенциальные проблемы с обратной совместимостью: если вам нужно показывать разные пейволы для разных версий приложения (текущей и будущих), могут возникнуть сложности. Придётся либо проектировать пейволы с поддержкой текущей (устаревшей) версии, либо смириться с тем, что пользователи этой версии могут столкнуться с проблемами при отображении пейволов.
- Потеря таргетинга: все пользователи будут видеть один и тот же пейвол, настроенный для аудитории All Users, — это означает отказ от персонализированного таргетинга (в том числе по странам, маркетинговой атрибуции или собственным пользовательским атрибутам).
Если вы готовы принять эти ограничения ради более быстрой загрузки пейвола, используйте метод getPaywallForDefaultAudience следующим образом. В противном случае придерживайтесь метода getPaywall, описанного выше.
Метод getPaywallForDefaultAudience доступен начиная с iOS SDK версии 2.11.2.
| Параметр | Наличие | Описание |
|---|---|---|
| placementId | обязательный | Идентификатор плейсмента. Это значение вы указали при создании плейсмента в дашборде Adapty. |
| locale | необязательный по умолчанию: | Идентификатор локализации пейвола. Ожидается, что этот параметр будет представлять собой код языка, состоящий из одного или нескольких подтегов, разделённых символом минуса (-). Первый подтег обозначает язык, второй — регион. Пример: Подробнее о кодах локалей и рекомендациях по их использованию см. в разделе Локализации и коды локалей. |
| fetchPolicy | по умолчанию: .reloadRevalidatingCacheData |
Однако если у ваших пользователей нестабильное интернет-соединение, рассмотрите Третья политика, Обратите внимание, что кэш сохраняется при перезапуске приложения и очищается только при его переустановке или вручную. |