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

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

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

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

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

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

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

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

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

try {
  final flow = await Adapty().getFlow(placementId: 'YOUR_PLACEMENT_ID');
  // the requested flow
} on AdaptyError catch (adaptyError) {
  // handle the error
} catch (e) {
  // handle the error
}

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

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

fetchPolicy

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

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

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

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

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

loadTimeout

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

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

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

В v4 метод getFlow не принимает параметр locale. Для кастомных пейволов все доступные локализации возвращаются в Remote Config флоу (flow.remoteConfigs) — выберите ту, которая соответствует языку устройства или настройкам приложения. См. Локализации и коды локалей.

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

Parameter	Description
Flow	Объект `AdaptyFlow` с идентификаторами флоу (`instanceIdentity`, `variationId`), именем, плейсментом, вариантами пейволов (`paywalls`) и Remote Config-ами (`remoteConfigs`).

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

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

try {
  final products = await Adapty().getPaywallProducts(flow: flow);
  // the requested products array
} on AdaptyError catch (adaptyError) {
  // handle the error
} catch (e) {
  // handle the error
}

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

Параметр	Описание
Products	Список объектов `AdaptyPaywallProduct` с: идентификатором продукта, названием продукта, ценой, валютой, длительностью подписки и рядом других свойств.
При реализации собственного дизайна пейвола вам, скорее всего, понадобится доступ к свойствам объекта `AdaptyPaywallProduct`. Ниже приведены наиболее часто используемые свойства; полный список доступных свойств см. в документации по ссылке.
Свойство	Описание
-------------------------	-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Title	Чтобы отобразить название продукта, используйте `product.localizedTitle`. Обратите внимание, что локализация основана на стране стора, выбранной пользователем, а не на локали самого устройства.
Price	Чтобы отобразить локализованную цену, используйте `product.price.localizedString`. Эта локализация основана на данных локали устройства. Цену в числовом виде можно получить через `product.price.amount`. Значение будет указано в местной валюте. Чтобы получить соответствующий символ валюты, используйте `product.price.currencySymbol`.
Subscription Period	Чтобы отобразить период (например, неделя, месяц, год и т.д.), используйте `product.subscription?.localizedPeriod`. Эта локализация основана на локали устройства. Чтобы получить период подписки программно, используйте `product.subscription?.period`. Оттуда можно обратиться к перечислению `unit`, чтобы получить длину периода (day, week, month, year или unknown). Значение `numberOfUnits` возвращает количество единиц периода. Например, для квартальной подписки в свойстве unit будет `AdaptyPeriodUnit.month`, а в numberOfUnits — `3`.
Introductory Offer	Чтобы отобразить значок или другой индикатор наличия introductory offer у подписки, проверьте свойство `product.subscription?.offer?.phases`. Это список, который может содержать до двух фаз скидки: фазу бесплатного пробного периода и фазу вводной цены. Каждый объект фазы содержит следующие полезные свойства: • `paymentMode`: перечисление со значениями `AdaptyPaymentMode.freeTrial`, `AdaptyPaymentMode.payAsYouGo`, `AdaptyPaymentMode.payUpFront` и `AdaptyPaymentMode.unknown`. Бесплатные пробные периоды имеют тип `AdaptyPaymentMode.freeTrial`. • `price`: цена со скидкой в числовом виде. Для бесплатных пробных периодов здесь будет `0`. • `localizedNumberOfPeriods`: строка, локализованная с учётом локали устройства, описывающая длительность предложения. Например, для трёхдневного пробного периода в этом поле будет `3 days`. • `subscriptionPeriod`: альтернативно можно получить отдельные детали периода предложения с помощью этого свойства. Оно работает так же, как описано в предыдущем разделе. • `localizedSubscriptionPeriod`: форматированный период подписки для скидки с учётом локали пользователя.

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

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

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

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

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

try {
  final flow = await Adapty().getFlowForDefaultAudience(placementId: 'YOUR_PLACEMENT_ID');
  // the requested flow
} on AdaptyError catch (adaptyError) {
  // handle error
} catch (e) {
  // handle unknown error
}

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

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

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

fetchPolicy

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

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

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

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

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

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

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

Получение данных о пейволе

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

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

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

try {
  final paywall = await Adapty().getPaywall(placementId: "YOUR_PLACEMENT_ID", locale: "en");
  // the requested paywall
} on AdaptyError catch (adaptyError) {
  // handle the error
} catch (e) {
}

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

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

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

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

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

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

try {
  final products = await Adapty().getPaywallProducts(paywall: paywall);
  // the requested products array
} on AdaptyError catch (adaptyError) {
  // handle the error
} catch (e) {
}

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

Параметр	Описание
Products	Список объектов `AdaptyPaywallProduct` со следующими свойствами: идентификатор продукта, название продукта, цена, валюта, длительность подписки и ряд других параметров.
При реализации собственного дизайна пейвола вам, скорее всего, потребуется доступ к свойствам объекта `AdaptyPaywallProduct`. Ниже приведены наиболее часто используемые свойства; полный список доступных свойств см. в документации по ссылке.
Свойство	Описание
-------------------------	----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Title	Чтобы отобразить название продукта, используйте `product.localizedTitle`. Локализация основана на выбранной пользователем стране в сторе, а не на локали устройства.
Price	Чтобы отобразить цену в локализованном формате, используйте `product.price.localizedString`. Локализация основана на локали устройства. Также можно получить цену как число через `product.price.amount` — значение будет в местной валюте. Чтобы получить символ валюты, используйте `product.price.currencySymbol`.
Subscription Period	Чтобы отобразить период (например, неделю, месяц, год и т. д.), используйте `product.subscription?.localizedPeriod`. Локализация основана на локали устройства. Чтобы получить период подписки программно, используйте `product.subscription?.period`. Оттуда можно обратиться к enum `unit`, чтобы получить единицу длительности (день, неделя, месяц, год или unknown). Значение `numberOfUnits` вернёт количество единиц периода. Например, для квартальной подписки в свойстве unit будет `AdaptyPeriodUnit.month`, а в numberOfUnits — `3`.
Introductory Offer	Чтобы отобразить бейдж или другой индикатор наличия introductory offer у подписки, проверьте свойство `product.subscription?.offer?.phases`. Это список, который может содержать до двух фаз скидки: фазу бесплатного пробного периода и фазу вводной цены. Каждый объект фазы содержит следующие полезные свойства: • `paymentMode`: enum со значениями `AdaptyPaymentMode.freeTrial`, `AdaptyPaymentMode.payAsYouGo`, `AdaptyPaymentMode.payUpFront` и `AdaptyPaymentMode.unknown`. Бесплатные пробные периоды имеют тип `AdaptyPaymentMode.freeTrial`. • `price`: скидочная цена в виде числа. Для бесплатных пробных периодов здесь будет `0`. • `localizedNumberOfPeriods`: строка, локализованная с учётом локали устройства и описывающая длительность предложения. Например, для трёхдневного пробного периода в этом поле будет `3 days`. • `subscriptionPeriod`: альтернативно можно получить отдельные детали периода предложения через это свойство — оно работает так же, как описано в предыдущем разделе. • `localizedSubscriptionPeriod`: форматированный период подписки скидки для локали пользователя.

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

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

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

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

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

try {
    final paywall = await Adapty().getPaywallForDefaultAudience(placementId: 'YOUR_PLACEMENT_ID');
} on AdaptyError catch (adaptyError) {
    // handle error
} catch (e) {
    // handle unknown error
}

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

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

locale

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

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

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

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

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

fetchPolicy

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

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

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

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