Получение пейволов и продуктов для пейволов с Remote Config в Kotlin Multiplatform SDK

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

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

1. Создайте продукты в дашборде Adapty.

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

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

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

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

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

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

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	По умолчанию SDK пытается загрузить данные с сервера и возвращает кэшированные данные в случае сбоя. Мы рекомендуем этот вариант, поскольку он гарантирует, что пользователи всегда получают актуальные данные. Однако если у ваших пользователей нестабильное интернет-соединение, рассмотрите использование AdaptyPaywallFetchPolicy.ReturnCacheDataElseLoad — оно возвращает кэшированные данные, если они есть. В этом случае пользователи могут получить не самые свежие данные, зато загрузка будет быстрее независимо от качества соединения. Кэш регулярно обновляется, поэтому его безопасно использовать в течение сессии, чтобы избежать лишних сетевых запросов. Обратите внимание: кэш сохраняется при перезапуске приложения и очищается только при его переустановке или принудительной очистке. Adapty SDK хранит флоу и пейволы в двух слоях: регулярно обновляемый кэш, описанный выше, и резервные пейволы. Для ускоренной загрузки флоу и пейволов используется CDN, а также отдельный резервный сервер на случай недоступности CDN. Такая система гарантирует, что вы всегда получаете актуальные версии флоу и пейволов, сохраняя надёжность даже при нестабильном интернете.
loadTimeout	по умолчанию: 5 сек	Это значение ограничивает таймаут метода. Если таймаут истекает, возвращаются кэшированные данные или локальный резервный вариант. Обратите внимание: в редких случаях метод может завершиться с небольшой задержкой относительно значения, указанного в loadTimeout, поскольку операция может состоять из нескольких внутренних запросов.

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

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

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

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

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

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, как описано в разделе Загрузка информации о флоу выше.

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

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

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

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

1. Создайте продукты в дашборде Adapty.

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

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

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

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

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

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

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	По умолчанию SDK пытается загрузить данные с сервера и возвращает кэшированные данные в случае ошибки. Мы рекомендуем этот вариант, поскольку он гарантирует, что пользователи всегда получают самые актуальные данные. Однако если у ваших пользователей нестабильное интернет-соединение, рассмотрите использование AdaptyPaywallFetchPolicy.ReturnCacheDataElseLoad — оно возвращает кэшированные данные, если они есть. В этом случае пользователи могут не получить самые последние данные, зато загрузка будет быстрее вне зависимости от качества соединения. Кэш регулярно обновляется, поэтому его безопасно использовать в течение сессии, чтобы избежать лишних сетевых запросов. Обратите внимание, что кэш сохраняется при перезапуске приложения и очищается только при его переустановке или вручную. Adapty SDK хранит пейволы в двух слоях: регулярно обновляемый кэш, описанный выше, и резервные пейволы. Также используется CDN для более быстрой загрузки пейволов и отдельный резервный сервер на случай недоступности 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, как описано в разделе Получение информации о пейволе выше.

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

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