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

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

Tip

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

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

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

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

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

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

Important

Не вшивайте 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.

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

fetchPolicy

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

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

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

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

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

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

loadTimeout

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

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

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

Note

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

Warning

Почему мы рекомендуем использовать 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.

fetchPolicy

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

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

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

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

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

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

Tip

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

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

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

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

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

Important

Не указывайте 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	по умолчанию: `AdaptyPaywallFetchPolicy.reloadRevalidatingCacheData`	`fetchPolicy` определяет, какой слой SDK читает первым, а не то, может ли он использовать кэш. По умолчанию SDK сначала обращается к серверу и возвращает кэшированные данные, если запрос завершился неудачей. Мы рекомендуем этот вариант, так как он гарантирует, что пользователи всегда получают актуальные данные. Однако если вы считаете, что у ваших пользователей нестабильное интернет-соединение, рассмотрите `AdaptyPaywallFetchPolicy.returnCacheDataElseLoad` — он меняет порядок на обратный: сначала читает кэш и обращается к серверу только при его отсутствии. Пользователи могут не получить самые свежие данные, но загрузка будет быстрее вне зависимости от качества соединения. Кэш обновляется регулярно, поэтому использовать его в рамках сессии для сокращения сетевых запросов безопасно. Третья политика, `AdaptyPaywallFetchPolicy.returnCacheDataIfNotExpiredElseLoad(maxAge)`, занимает промежуточное положение: она читает кэш, пока его возраст меньше переданного значения `Duration`, и обращается к серверу, когда кэш устаревает. Обратите внимание: кэш сохраняется после перезапуска приложения и очищается только при переустановке или вручную. Adapty SDK хранит пейволы на двух уровнях: регулярно обновляемый кэш, описанный выше, и резервные пейволы. Также используется CDN для ускорения загрузки и отдельный резервный сервер на случай недоступности CDN. Эта система гарантирует, что вы всегда получаете актуальную версию пейволов, обеспечивая надёжность даже при слабом интернет-соединении.
loadTimeout	по умолчанию: 5 сек	Это значение ограничивает тайм-аут метода. При его истечении будут возвращены кэшированные данные или локальный резервный пейвол. Обратите внимание: в редких случаях метод может завершиться с тайм-аутом немного позже указанного в `loadTimeout` значения, поскольку операция может включать несколько запросов под капотом.

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

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

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

Параметр	Описание
Paywall	Объект `AdaptyPaywall` со списком ID продуктов, идентификатором пейвола, 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, как описано в разделе Получение информации о пейволе выше.

Warning

Почему мы рекомендуем использовать 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
}

Note

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

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

locale

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

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

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

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

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

fetchPolicy

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

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

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

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

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