Получение кастомных пейволов и продуктов в iOS SDK

Прежде чем отображать кастомные пейволы, необходимо получить информацию о них. Обратите внимание, что данный раздел посвящён кастомным пейволам. Если вы используете флоу или пейволы, созданные в Flow & Paywall Builder или old Paywall Builder, обратитесь к гайдам по получению флоу и пейволов в приложении .

Tip

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

Прежде чем начать получать флоу и продукты в мобильном приложении (нажмите, чтобы развернуть)
  1. Создайте продукты в дашборде Adapty.

  2. Создайте флоу или пейвол и добавьте в него продукты в дашборде Adapty.

  3. Создайте плейсменты и добавьте флоу или пейвол в плейсмент в дашборде Adapty.

  4. Установите Adapty SDK в мобильном приложении.

Получение информации о флоу

В Adapty продукт объединяет в себе продукты из App Store и Google Play. Эти кросс-платформенные продукты интегрируются во флоу и пейволы, позволяя демонстрировать их в конкретных плейсментах мобильного приложения.

Чтобы отобразить продукты, необходимо получить AdaptyFlow из одного из ваших плейсментов с помощью метода getFlow.

Important

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

ПараметрНаличиеОписание
placementIdобязательныйИдентификатор плейсмента. Это значение вы указывали при создании плейсмента в дашборде Adapty.
fetchPolicyпо умолчанию: .reloadRevalidatingCacheData

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

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

Третья политика, .returnCacheDataIfNotExpiredElseLoad(maxAge:), занимает промежуточное положение: она читает кэш, пока его возраст меньше maxAge секунд, и обращается к серверу, если кэш устарел.

Обратите внимание, что кэш сохраняется при перезапуске приложения и очищается только при его переустановке или вручную.

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

loadTimeoutпо умолчанию: 5 сек

Это значение ограничивает таймаут данного метода. Если сервер Adapty не отвечает вовремя или возвращает ошибку, SDK возвращает кэшированный флоу. Если кэша нет, а сервер не ответил или вернул ошибку, SDK запрашивает флоу с резервного сервера (CDN-копия, которая обслуживает только аудиторию All Users данного плейсмента). В крайнем случае SDK возвращает флоу из вашего резервного файла.

Обратите внимание, что в редких случаях метод может завершиться чуть позже указанного в loadTimeout времени, поскольку операция может состоять из нескольких запросов под капотом.

Note

В v4 параметр locale перенесён из getFlow в getFlowConfiguration (используется только при рендеринге через AdaptyUI). Для кастомных пейволов все доступные локали возвращаются вместе в flow.remoteConfigs — выберите ту, которая соответствует языку устройства пользователя или настройкам вашего приложения.

Tip

Чтобы заполнить кэш до того, как пользователь откроет флоу, вызовите 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: отформатированный период подписки скидки для локали пользователя.
Note

В v4 все продукты, возвращаемые методом getPaywallProducts(flow:), уже содержат информацию о подходящих офферах. Отдельный вызов getPaywallProductsWithoutDeterminingOffer из v3 был удалён.

Ускорьте загрузку флоу с помощью флоу для аудитории по умолчанию

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

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

Warning

Почему мы рекомендуем использовать getFlow

Метод getFlowForDefaultAudience имеет ряд существенных недостатков:

  • Возможные проблемы с обратной совместимостью: если вам нужно показывать разные флоу для разных версий приложения (текущей и будущих), могут возникнуть сложности. Придётся либо проектировать флоу с поддержкой текущей (устаревшей) версии, либо мириться с тем, что пользователи на этой версии могут столкнуться с нерендерящимися флоу.
  • Потеря таргетинга: все пользователи будут видеть один и тот же флоу, настроенный для аудитории All Users, — а значит, вы теряете персонализированный таргетинг (в том числе по странам, маркетинговой атрибуции или собственным кастомным атрибутам).

Если вас устраивают эти недостатки ради более быстрой загрузки флоу, используйте метод getFlowForDefaultAudience следующим образом. В противном случае придерживайтесь метода getFlow, описанного выше.

ПараметрНаличиеОписание
placementIdобязательныйИдентификатор плейсмента. Это значение вы указали при создании плейсмента в дашборде Adapty.
fetchPolicyпо умолчанию: .reloadRevalidatingCacheData

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

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

Третья политика, .returnCacheDataIfNotExpiredElseLoad(maxAge:), занимает промежуточное положение: она сначала читает кэш, пока кэшированная копия моложе maxAge секунд, и обращается к серверу, когда кэш устарел.

Обратите внимание, что кэш сохраняется при перезапуске приложения и очищается только при его переустановке или вручную.

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

Tip

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

Прежде чем начать получать пейволы и продукты в мобильном приложении (нажмите, чтобы развернуть)
  1. Создайте продукты в дашборде Adapty.

  2. Создайте пейвол и добавьте в него продукты в дашборде Adapty.

  3. Создайте плейсменты и добавьте пейвол в плейсмент в дашборде Adapty.

  4. Установите Adapty SDK в мобильном приложении.

Получение информации о пейволе

В Adapty продукт объединяет продукты из App Store и Google Play. Эти кросс-платформенные продукты добавляются в пейволы, что позволяет показывать их в нужных плейсментах мобильного приложения.

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

Important

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

ПараметрНаличиеОписание
placementIdобязательныйИдентификатор плейсмента. Это значение вы указали при создании плейсмента в дашборде Adapty.
locale

необязательный

по умолчанию: en

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

Пример: en означает английский, pt-br — бразильский португальский.

Подробнее о кодах локалей и рекомендациях по их использованию см. в разделе Локализации и коды локалей.

fetchPolicyпо умолчанию: .reloadRevalidatingCacheData

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

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

Третья политика, .returnCacheDataIfNotExpiredElseLoad(maxAge:), находится между двумя первыми: она читает кэш, пока его возраст меньше maxAge секунд, и обращается к серверу, когда он становится старше.

Обратите внимание, что кэш сохраняется при перезапуске приложения и очищается только при переустановке или ручной очистке.

Adapty SDK хранит пейволы в двух слоях: регулярно обновляемый кэш, описанный выше, и резервные пейволы. Мы также используем CDN для ускорения загрузки пейволов и отдельный резервный сервер на случай недоступности CDN. Эта система обеспечивает получение актуальной версии пейволов и надёжность даже при плохом интернет-соединении.

loadTimeoutпо умолчанию: 5 сек

Это значение ограничивает таймаут для данного метода. Если сервер Adapty не отвечает вовремя или возвращает ошибку, SDK возвращает пейвол с резервного сервера (копия CDN, обслуживающая только аудиторию All Users плейсмента), из кэша или из вашего резервного файла.

Обратите внимание, что в редких случаях метод может завершиться по таймауту чуть позже, чем указано в loadTimeout, поскольку операция может состоять из нескольких внутренних запросов.

Не задавайте 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.

Note

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

Ускорьте загрузку пейвола с помощью пейвола для аудитории по умолчанию

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

Чтобы решить эту задачу, можно использовать метод getPaywallForDefaultAudience, который загружает пейвол указанного плейсмента для аудитории All Users. Однако важно понимать, что рекомендуемый подход — загружать пейвол с помощью метода getPaywall, как описано в разделе Получение информации о пейволе выше.

Warning

Почему мы рекомендуем использовать getPaywall

Метод getPaywallForDefaultAudience имеет ряд существенных недостатков:

  • Потенциальные проблемы с обратной совместимостью: если вам нужно показывать разные пейволы для разных версий приложения (текущей и будущих), могут возникнуть сложности. Придётся либо проектировать пейволы с поддержкой текущей (устаревшей) версии, либо смириться с тем, что пользователи этой версии могут столкнуться с проблемами при отображении пейволов.
  • Потеря таргетинга: все пользователи будут видеть один и тот же пейвол, настроенный для аудитории All Users, — это означает отказ от персонализированного таргетинга (в том числе по странам, маркетинговой атрибуции или собственным пользовательским атрибутам).

Если вы готовы принять эти ограничения ради более быстрой загрузки пейвола, используйте метод getPaywallForDefaultAudience следующим образом. В противном случае придерживайтесь метода getPaywall, описанного выше.

Note

Метод getPaywallForDefaultAudience доступен начиная с iOS SDK версии 2.11.2.

ПараметрНаличиеОписание
placementIdобязательныйИдентификатор плейсмента. Это значение вы указали при создании плейсмента в дашборде Adapty.
locale

необязательный

по умолчанию: en

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

Пример: en означает английский, pt-br — бразильский португальский.

Подробнее о кодах локалей и рекомендациях по их использованию см. в разделе Локализации и коды локалей.

fetchPolicyпо умолчанию: .reloadRevalidatingCacheData

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

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

Третья политика, .returnCacheDataIfNotExpiredElseLoad(maxAge:), занимает промежуточное положение: она читает кэш, пока его возраст не превышает maxAge секунд, и обращается к серверу, как только кэш устаревает.

Обратите внимание, что кэш сохраняется при перезапуске приложения и очищается только при его переустановке или вручную.