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

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

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

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

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

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

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

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

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

Adapty.getFlow("YOUR_PLACEMENT_ID") { result ->
    when (result) {
        is AdaptyResult.Success -> {
            val flow = result.value
            // the requested flow
        }
        is AdaptyResult.Error -> {
            val error = result.error
            // handle the error
        }
    }
}

Adapty.getFlow("YOUR_PLACEMENT_ID", result -> {
    if (result instanceof AdaptyResult.Success) {
        AdaptyFlow flow = ((AdaptyResult.Success<AdaptyFlow>) result).getValue();
        // the requested flow
      
    } else if (result instanceof AdaptyResult.Error) {
        AdaptyError error = ((AdaptyResult.Error) result).getError();
        // handle the error
      
    }
});

Параметр	Наличие	Описание
placementId	обязательный	Идентификатор плейсмента. Это значение вы указали при создании плейсмента в дашборде Adapty.
loadTimeout	по умолчанию: 5 сек	Это значение ограничивает тайм-аут метода. При его истечении будут возвращены кешированные данные или локальный фолбэк. Обратите внимание: в редких случаях метод может завершиться с небольшой задержкой относительно значения `loadTimeout`, поскольку операция может включать несколько запросов.
Не задавайте product ID жёстко в коде! Так как флоу настраиваются удалённо, набор доступных продуктов, их количество и специальные предложения (например, бесплатные пробные периоды) могут меняться со временем. Убедитесь, что ваш код учитывает эти сценарии.
Например, если изначально вы получаете 2 продукта, приложение должно отображать эти 2 продукта. Но если позже вы получите 3 продукта, приложение должно показать все 3 без каких-либо изменений в коде. Единственное, что нужно задать жёстко, — это ID плейсмента.

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

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

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

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

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

Adapty.getPaywallProducts(flow) { result ->
    when (result) {
        is AdaptyResult.Success -> {
            val products = result.value
            // the requested products
        }
        is AdaptyResult.Error -> {
            val error = result.error
            // handle the error
        }
    }
}

Adapty.getPaywallProducts(flow, result -> {
    if (result instanceof AdaptyResult.Success) {
        List<AdaptyPaywallProduct> products = ((AdaptyResult.Success<List<AdaptyPaywallProduct>>) result).getValue();
        // запрошенные продукты
      
    } else if (result instanceof AdaptyResult.Error) {
        AdaptyError error = ((AdaptyResult.Error) result).getError();
        // обработка ошибки
      
    }
});

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

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

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

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

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

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

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

Adapty.getFlowForDefaultAudience("YOUR_PLACEMENT_ID") { result ->
    when (result) {
        is AdaptyResult.Success -> {
            val flow = result.value
            // the requested flow
        }
        is AdaptyResult.Error -> {
            val error = result.error
            // handle the error
        }
    }
}

Adapty.getFlowForDefaultAudience("YOUR_PLACEMENT_ID", result -> {
    if (result instanceof AdaptyResult.Success) {
        AdaptyFlow flow = ((AdaptyResult.Success<AdaptyFlow>) result).getValue();
        // запрошенный флоу
      
    } else if (result instanceof AdaptyResult.Error) {
        AdaptyError error = ((AdaptyResult.Error) result).getError();
        // обработайте ошибку
      
    }
});

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

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

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

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

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

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

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

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

Adapty.getPaywall("YOUR_PLACEMENT_ID", locale = "en") { result ->
    when (result) {
        is AdaptyResult.Success -> {
            val paywall = result.value
            // the requested paywall
        }
        is AdaptyResult.Error -> {
            val error = result.error
            // handle the error
        }
    }
}

Adapty.getPaywall("YOUR_PLACEMENT_ID", "en", result -> {
    if (result instanceof AdaptyResult.Success) {
        AdaptyPaywall paywall = ((AdaptyResult.Success<AdaptyPaywall>) result).getValue();
        // the requested paywall
      
    } else if (result instanceof AdaptyResult.Error) {
        AdaptyError error = ((AdaptyResult.Error) result).getError();
        // handle the error
      
    }
});

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

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

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

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

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

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

Adapty.getPaywallProducts(paywall) { result ->
    when (result) {
        is AdaptyResult.Success -> {
            val products = result.value
            // the requested products
        }
        is AdaptyResult.Error -> {
            val error = result.error
            // handle the error
        }
    }
}

Adapty.getPaywallProducts(paywall, result -> {
    if (result instanceof AdaptyResult.Success) {
        List<AdaptyPaywallProduct> products = ((AdaptyResult.Success<List<AdaptyPaywallProduct>>) result).getValue();
        // the requested products
      
    } else if (result instanceof AdaptyResult.Error) {
        AdaptyError error = ((AdaptyResult.Error) result).getError();
        // 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, как описано в разделе Получение информации о пейволе выше.

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

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

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

Adapty.getPaywallForDefaultAudience("YOUR_PLACEMENT_ID", locale = "en") { result ->
    when (result) {
        is AdaptyResult.Success -> {
            val paywall = result.value
            // the requested paywall
        }
        is AdaptyResult.Error -> {
            val error = result.error
            // handle the error
        }
    }
}

Adapty.getPaywallForDefaultAudience("YOUR_PLACEMENT_ID", "en", result -> {
    if (result instanceof AdaptyResult.Success) {
        AdaptyPaywall paywall = ((AdaptyResult.Success<AdaptyPaywall>) result).getValue();
        // the requested paywall
      
    } else if (result instanceof AdaptyResult.Error) {
        AdaptyError error = ((AdaptyResult.Error) result).getError();
        // handle the error
      
    }
});

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

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

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

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

locale

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

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

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

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

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

fetchPolicy

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

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

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

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