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

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

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

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

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

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

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

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

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

try {
  final paywall = await Adapty().getPaywall(id: "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 продукта, приложение должно отображать их. Но если позже вы получите 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`. Из него можно получить перечисление `unit` для определения длины (день, неделя, месяц, год или 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`: отформатированный период подписки скидки для локали пользователя.

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

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

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

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

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

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

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

Метод getPaywallForDefaultAudience пока не поддерживается в Flutter SDK, но поддержка будет добавлена в ближайшее время.

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

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

locale

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

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

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

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

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

fetchPolicy

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

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

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

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