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

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

Tip

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

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

Создайте продукты в дашборде Adapty.
Создайте флоу или пейвол и добавьте в него продукты в дашборде Adapty.
Создайте плейсменты и добавьте в них флоу или пейвол в дашборде Adapty.
Установите Adapty SDK в своё мобильное приложение.

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

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

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

Important

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


Adapty.getFlow(
    placementId = "YOUR_PLACEMENT_ID", 
    fetchPolicy = AdaptyPaywallFetchPolicy.Default,
    loadTimeout = 5.seconds
).onSuccess { flow ->
    // the requested flow
}.onError { error ->
    // handle the error
}

Параметр Обязательность Описание

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

fetchPolicy

по умолчанию: AdaptyPaywallFetchPolicy.Default

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

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

Третья политика, AdaptyPaywallFetchPolicy.ReturnCacheDataIfNotExpiredElseLoad(maxAgeMillis), находится между двумя предыдущими: она читает кеш, пока он свежее maxAgeMillis, и обращается к серверу, как только кеш устаревает.

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

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

loadTimeout

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

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

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

Не указывайте идентификаторы продуктов в коде! Поскольку флоу настраиваются удалённо, набор доступных продуктов, их количество и специальные предложения (например, бесплатные пробные периоды) могут меняться со временем. Убедитесь, что ваш код учитывает эти сценарии.
Например, если изначально вы получаете 2 продукта, приложение должно отображать именно 2. Но если позднее вы получите 3 продукта, приложение должно показать все 3 без каких-либо изменений в коде. Единственное, что нужно зафиксировать в коде, — это идентификатор плейсмента.

Параметры ответа:

Параметр	Описание
Flow	Объект `AdaptyFlow` с: идентификатором флоу, вариантами пейвола (`paywalls` — каждый со своими идентификаторами продуктов), списком `remoteConfigs` (по одной записи на каждую настроенную локаль) и рядом других свойств. Чтобы получить продукты для флоу, вызовите `getPaywallProducts(flow)`.

Note

В v4 у getFlow нет параметра locale. При рендеринге флоу с помощью createFlowView локализация определяется автоматически. Для кастомных пейволов все доступные локали возвращаются вместе в flow.remoteConfigs — выберите локаль, соответствующую устройству пользователя или настройкам вашего приложения. Подробнее см. в разделе Локализации и коды локалей.

Получение продуктов

Получив флоу, можно запросить массив продуктов, соответствующих ему:

Adapty.getPaywallProducts(flow).onSuccess { products ->
    // the requested products
}.onError { error ->
    // handle the error
}

Параметры ответа:

Параметр	Описание
Products	Список объектов `AdaptyPaywallProduct` с идентификатором продукта, названием продукта, ценой, валютой, длительностью подписки и рядом других свойств.

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

Свойство	Описание
Title	Чтобы отобразить название продукта, используйте `product.localizedTitle`. Локализация определяется страной стора, выбранной пользователем, а не локалью устройства.
Price	Чтобы отобразить цену в локализованном виде, используйте `product.price.localizedString`. Локализация определяется локалью устройства. Цену в виде числа можно получить через `product.price.amount` — значение будет в местной валюте. Чтобы получить символ валюты, используйте `product.price.currencySymbol`.
Subscription Period	Чтобы отобразить период (например, неделя, месяц, год и т. д.), используйте `product.subscriptionDetails?.localizedSubscriptionPeriod`. Локализация определяется локалью устройства. Чтобы получить период подписки программно, используйте `product.subscriptionDetails?.subscriptionPeriod`. Из него можно получить enum `unit`, определяющий длину периода (DAY, WEEK, MONTH, YEAR или UNKNOWN). Значение `numberOfUnits` содержит количество единиц периода. Например, для квартальной подписки в свойстве `unit` будет `MONTH`, а в `numberOfUnits` — `3`.
Introductory Offer	Чтобы отобразить значок или другой индикатор наличия introductory offer у подписки, проверьте свойство `product.subscriptionDetails?.introductoryOfferPhases`. Это список, который может содержать до двух фаз скидки: фазу бесплатного пробного периода и фазу вводной цены. В каждом объекте фазы доступны следующие полезные свойства: • `paymentMode` — enum со значениями `FREE_TRIAL`, `PAY_AS_YOU_GO`, `PAY_UPFRONT` и `UNKNOWN`. Бесплатные пробные периоды имеют тип `FREE_TRIAL`. • `price` — цена со скидкой в виде числа. Для бесплатных пробных периодов здесь будет `0`. • `localizedNumberOfPeriods` — строка, локализованная по локали устройства и описывающая длину предложения. Например, для трёхдневного пробного периода в этом поле отобразится `3 days`. • `subscriptionPeriod` — позволяет получить детали периода предложения по отдельности. Работает так же, как описано в предыдущем разделе. • `localizedSubscriptionPeriod` — отформатированный период подписки по скидке для локали пользователя.

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

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

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

Warning

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

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

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

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


Adapty.getFlowForDefaultAudience(
    placementId = "YOUR_PLACEMENT_ID",
    fetchPolicy = AdaptyPaywallFetchPolicy.Default
).onSuccess { flow ->
    // the requested flow
}.onError { error ->
    // handle the error
}

Параметр Наличие Описание

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

Параметр	Наличие	Описание
placementId	обязательный	Идентификатор плейсмента. Это значение вы указывали при создании плейсмента в дашборде Adapty.
fetchPolicy	по умолчанию: `AdaptyPaywallFetchPolicy.Default`	`fetchPolicy` определяет, какой слой SDK читает первым, а не то, может ли он использовать кеш. По умолчанию SDK сначала обращается к серверу и возвращает кешированные данные, если запрос не удался. Мы рекомендуем этот вариант, так как он гарантирует, что пользователи всегда получают актуальные данные. Однако если у ваших пользователей нестабильный интернет, рассмотрите `AdaptyPaywallFetchPolicy.ReturnCacheDataElseLoad` — он меняет порядок на обратный: сначала читает кеш и обращается к серверу только при его отсутствии. Пользователи могут не получить самые свежие данные, зато загрузка будет быстрее вне зависимости от качества соединения. Кеш обновляется регулярно, поэтому его безопасно использовать в течение сессии, чтобы избежать лишних сетевых запросов. Третья политика, `AdaptyPaywallFetchPolicy.ReturnCacheDataIfNotExpiredElseLoad(maxAgeMillis)`, занимает промежуточное положение: она читает кеш, пока его возраст меньше `maxAgeMillis`, и обращается к серверу, когда кеш устарел. Обратите внимание: кеш сохраняется после перезапуска приложения и очищается только при его переустановке или ручной очистке.

fetchPolicy

по умолчанию: AdaptyPaywallFetchPolicy.Default

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

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

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

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

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

Tip

Прежде чем начать получать пейволы и продукты в своём мобильном приложении (нажмите, чтобы развернуть)

Создайте продукты в дашборде Adapty.
Создайте пейвол и добавьте продукты в него в дашборде Adapty.
Создайте плейсменты и добавьте пейвол в плейсмент в дашборде Adapty.
Установите SDK Adapty в своё мобильное приложение.

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

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

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

Important

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


Adapty.getPaywall(
    placementId = "YOUR_PLACEMENT_ID", 
    locale = "en",
    fetchPolicy = AdaptyPaywallFetchPolicy.Default,
    loadTimeout = 5.seconds
).onSuccess { paywall ->
    // the requested paywall
}.onError { error ->
    // handle the error
}

Параметр	Наличие	Описание
placementId	обязательный	Идентификатор плейсмента. Это значение вы указали при создании плейсмента в дашборде Adapty.
locale	опциональный по умолчанию: `en`	Идентификатор локализации пейвола. Ожидается в виде языкового кода, состоящего из одного или нескольких подтегов, разделённых символом минус (-). Первый подтег обозначает язык, второй — регион. Например: `en` — английский, `pt-br` — бразильский португальский.
fetchPolicy	по умолчанию: `AdaptyPaywallFetchPolicy.Default`	`fetchPolicy` определяет, какой слой SDK читает первым, а не возможность использования кэша как такового. По умолчанию SDK обращается сначала к серверу и возвращает кэшированные данные, если запрос не удался. Мы рекомендуем этот вариант, поскольку он гарантирует, что пользователи всегда получают актуальные данные. Однако если вы считаете, что ваши пользователи работают в условиях нестабильного интернета, рассмотрите `AdaptyPaywallFetchPolicy.ReturnCacheDataElseLoad` — он меняет порядок на обратный: сначала читает кэш и обращается к серверу только при его отсутствии. Пользователи могут не получить самые свежие данные, зато загрузка будет быстрее вне зависимости от качества соединения. Кэш регулярно обновляется, поэтому его безопасно использовать в течение сессии, чтобы избежать лишних сетевых запросов. Третья политика, `AdaptyPaywallFetchPolicy.ReturnCacheDataIfNotExpiredElseLoad(maxAgeMillis)`, занимает промежуточное положение: она читает кэш, пока его возраст меньше `maxAgeMillis`, и обращается к серверу, когда кэш устарел. Обратите внимание, что кэш сохраняется при перезапуске приложения и очищается только при его переустановке или вручную. Adapty SDK хранит пейволы на двух уровнях: регулярно обновляемый кэш, описанный выше, и резервные пейволы. Для ускорения загрузки пейволов также используется CDN, а в случае его недоступности — отдельный резервный сервер. Эта система обеспечивает актуальность пейволов и надёжность даже при плохом интернет-соединении.
loadTimeout	по умолчанию: 5 сек	Ограничивает тайм-аут этого метода. По истечении тайм-аута будут возвращены кэшированные данные или локальный резервный пейвол. Обратите внимание, что в редких случаях метод может завершиться с небольшой задержкой относительно значения, указанного в `loadTimeout`, поскольку операция может включать несколько внутренних запросов.

Не прописывайте идентификаторы продуктов в коде! Поскольку пейволы настраиваются удалённо, список доступных продуктов, их количество и специальные предложения (например, бесплатные пробные периоды) могут меняться со временем. Убедитесь, что ваш код учитывает эти сценарии.

Например, если изначально вы получаете 2 продукта, приложение должно показывать 2 продукта. Но если позже вы получите 3 продукта, приложение должно отображать все 3 без каких-либо изменений в коде. Единственное, что нужно прописать в коде, — это идентификатор плейсмента.

Параметры ответа:

Параметр	Описание
Paywall	Объект `AdaptyPaywall` со списком идентификаторов продуктов, идентификатором пейвола, Remote Config и рядом других свойств.

Получение продуктов

Получив пейвол, вы можете запросить массив продуктов, соответствующих ему:

Adapty.getPaywallProducts(paywall).onSuccess { products ->
    // the requested products
}.onError { error ->
    // handle the error
}

Параметры ответа:

Параметр	Описание
Products	Список объектов `AdaptyPaywallProduct` с: идентификатором продукта, названием продукта, ценой, валютой, длительностью подписки и рядом других свойств.

При реализации собственного дизайна пейвола вам, скорее всего, понадобятся следующие свойства объекта AdaptyPaywallProduct. Ниже приведены наиболее часто используемые свойства; полный список доступных свойств см. в связанной документации.

Свойство	Описание
Title	Чтобы отобразить название продукта, используйте `product.localizedTitle`. Локализация основана на стране стора, выбранной пользователем, а не на локали устройства.
Price	Чтобы отобразить локализованную цену, используйте `product.price.localizedString`. Локализация основана на локали устройства. Цену также можно получить как число через `product.price.amount` — значение будет в местной валюте. Символ валюты доступен через `product.price.currencySymbol`.
Subscription Period	Чтобы отобразить период подписки (например, неделя, месяц, год и т. д.), используйте `product.subscriptionDetails?.localizedSubscriptionPeriod`. Локализация основана на локали устройства. Для программного получения периода подписки используйте `product.subscriptionDetails?.subscriptionPeriod`. Оттуда можно обратиться к enum `unit`, чтобы узнать длину периода (DAY, WEEK, MONTH, YEAR или UNKNOWN). Значение `numberOfUnits` содержит количество единиц периода. Например, для квартальной подписки в свойстве `unit` будет `MONTH`, а в `numberOfUnits` — `3`.
Introductory Offer	Чтобы показать значок или другой индикатор наличия introductory offer у подписки, проверьте свойство `product.subscriptionDetails?.introductoryOfferPhases`. Это список, который может содержать до двух фаз скидки: фазу бесплатного пробного периода и фазу вступительной цены. Каждый объект фазы содержит следующие полезные свойства: • `paymentMode`: enum со значениями `FREE_TRIAL`, `PAY_AS_YOU_GO`, `PAY_UPFRONT` и `UNKNOWN`. Бесплатный пробный период соответствует типу `FREE_TRIAL`. • `price`: сниженная цена как число. Для бесплатных пробных периодов здесь будет `0`. • `localizedNumberOfPeriods`: строка, локализованная по локали устройства, описывающая длительность предложения. Например, для трёхдневного пробного периода в этом поле будет `3 days`. • `subscriptionPeriod`: позволяет получить отдельные детали периода предложения — работает так же, как описано в предыдущем разделе. • `localizedSubscriptionPeriod`: отформатированный период подписки скидки для локали пользователя.

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

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

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

Warning

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

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

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

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


Adapty.getPaywallForDefaultAudience(
    placementId = "YOUR_PLACEMENT_ID",
    locale = "en",
    fetchPolicy = AdaptyPaywallFetchPolicy.Default
).onSuccess { paywall ->
    // the requested paywall
}.onError { error ->
    // handle the error
}

Параметр Наличие Описание

locale

опциональный

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

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

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

fetchPolicy

по умолчанию: AdaptyPaywallFetchPolicy.Default

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

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

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

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