Получение пользовательских пейволов и продуктов в React Native SDK

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

Tip

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

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

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

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

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

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

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

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

Important

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

try {
    const id = 'YOUR_PLACEMENT_ID';

    const flow = await adapty.getFlow(id);
    // the requested flow
} catch (error) {
    // handle the error
}
ПараметрНаличиеОписание
placementIdобязательныйИдентификатор плейсмента. Это значение вы указали при создании плейсмента в дашборде Adapty.
fetchPolicyпо умолчанию: 'reload_revalidating_cache_data'

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

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

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

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

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

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

Это значение ограничивает таймаут метода. Если сервер Adapty не отвечает вовремя или возвращает ошибку, SDK возвращает кэшированный флоу. Если кэш пуст, а сервер завершился по таймауту или вернул ошибку, SDK запрашивает флоу с резервного сервера (CDN-копия, которая обслуживает только аудиторию All Users плейсмента). В крайнем случае SDK возвращает флоу из вашего резервного файла.

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

Tip

Чтобы заполнить кэш до того, как пользователь откроет флоу, вызовите preloadFlows (React Native SDK 4.3.0+) для нескольких плейсментов сразу. Передайте fetchPolicy: 'return_cache_data_else_load', чтобы читать из кэша раньше, чем обращаться к сети.

Note

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

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

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

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

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

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

try {
    // ...flow
    const products = await adapty.getPaywallProducts(flow);
  // the requested products list
} catch (error) {
    // handle the error
}

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

ParameterDescription
ProductsСписок объектов AdaptyPaywallProduct с: идентификатором продукта, названием продукта, ценой, валютой, длительностью подписки и рядом других свойств.

При реализации собственного дизайна пейвола вам, скорее всего, потребуется доступ к свойствам объекта AdaptyPaywallProduct. Ниже показаны наиболее часто используемые свойства, но полный список всех доступных свойств см. в документации по ссылке.

СвойствоОписание
TitleДля отображения названия продукта используйте product.localizedTitle. Обратите внимание, что локализация основана на стране стора, выбранной пользователем, а не на локали самого устройства.
PriceДля отображения локализованной цены используйте product.price?.localizedString. Локализация основана на настройках локали устройства. Цену в виде числа можно получить через product.price?.amount. Значение будет в местной валюте. Символ валюты доступен через product.price?.currencySymbol.
Subscription PeriodДля отображения периода (например, неделя, месяц, год и т. д.) используйте product.subscription?.localizedSubscriptionPeriod. Локализация основана на локали устройства. Чтобы получить период подписки программно, используйте product.subscription?.subscriptionPeriod. Из этого объекта можно получить свойство unit — длину единицы периода ('day', 'week', 'month', 'year' или 'unknown'). Свойство numberOfUnits возвращает количество таких единиц. Например, для квартальной подписки в свойстве unit будет 'month', а в numberOfUnits — 3.
Billing planТолько iOS. Для продукта с 12-месячным обязательством используйте product.subscription?.ios?.pricingTerms, чтобы отобразить обе цены, которые требует Apple: billingPrice.localizedString и billingPeriod — для ежемесячного платежа, commitmentInfo.price.localizedString и commitmentInfo.period — для итоговой годовой суммы. billingPlan имеет значение 'monthly' для плана с обязательством и 'up_front' в остальных случаях. Для плана с обязательством product.price и product.subscription?.subscriptionPeriod возвращают годовую сумму и период, а не размер отдельного платежа. Требуется Adapty SDK версии 4.3.0 или выше.
Introductory OfferЧтобы показать бейдж или другой индикатор наличия introductory offer в подписке, проверьте свойство product.subscription?.offer?.phases. Это список, который может содержать до двух фаз скидки: фазу бесплатного пробного периода и фазу вступительной цены. Каждый объект фазы содержит следующие полезные свойства:
• paymentMode: строка со значениями 'free_trial', 'pay_as_you_go', 'pay_up_front' и 'unknown'. Бесплатные пробные периоды имеют тип 'free_trial'.
• price: сниженная цена в виде числа. Для бесплатных пробных периодов здесь будет 0.
• localizedNumberOfPeriods: строка, локализованная в соответствии с локалью устройства, описывающая длительность предложения. Например, для трёхдневного пробного периода в этом поле будет '3 days'.
• subscriptionPeriod: альтернативный способ получить отдельные детали периода предложения. Работает аналогично тому, как описано в предыдущем разделе.
• localizedSubscriptionPeriod: отформатированный период подписки для скидки в локали пользователя.

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

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

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

Warning

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

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

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

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

try {
    const id = 'YOUR_PLACEMENT_ID';

    const flow = await adapty.getFlowForDefaultAudience(id);
  // the requested flow
} catch (error) {
    // handle the error
}
ПараметрНаличиеОписание
placementIdобязательныйИдентификатор плейсмента. Это значение вы указываете при создании плейсмента в дашборде Adapty.
fetchPolicyпо умолчанию: 'reload_revalidating_cache_data'

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

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

Третья политика, 'return_cache_data_if_not_expired_else_load', занимает промежуточное положение: она читает кеш, пока его возраст меньше значения maxAgeSeconds, переданного вместе с ней, и обращается к серверу, когда кеш устарел.

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

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

Tip

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

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

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

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

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

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

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

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

Important

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

try {
    const id = 'YOUR_PLACEMENT_ID';
    const locale = 'en';

    const paywall = await adapty.getPaywall(id, locale);
    // the requested paywall
} catch (error) {
    // handle the error
}
ПараметрНаличиеОписание
placementIdобязательныйИдентификатор плейсмента. Это значение вы указали при создании плейсмента в дашборде Adapty.
locale

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

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

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

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

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

fetchPolicyпо умолчанию: 'reload_revalidating_cache_data'

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

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

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

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

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

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

Это значение ограничивает таймаут для данного метода. Если сервер Adapty не отвечает вовремя или возвращает ошибку, SDK возвращает пейвол с резервного сервера (копия CDN, обслуживающая только аудиторию All Users плейсмента), из кэша или из вашего резервного файла.

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

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

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

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

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

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

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

try {
    // ...paywall
    const products = await adapty.getPaywallProducts(paywall);
  // the requested products list
} catch (error) {
    // handle the error
}

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

ПараметрОписание
ProductsСписок объектов AdaptyPaywallProduct с идентификатором продукта, названием продукта, ценой, валютой, длительностью подписки и рядом других свойств.

При реализации собственного дизайна пейвола вам, скорее всего, понадобятся свойства объекта AdaptyPaywallProduct. Ниже приведены наиболее часто используемые свойства; полный список доступных свойств смотрите в документации по ссылке.

СвойствоОписание
TitleЧтобы отобразить название продукта, используйте product.localizedTitle. Обратите внимание, что локализация основана на стране стора, выбранной пользователем, а не на языке устройства.
PriceЧтобы отобразить локализованную цену, используйте product.price?.localizedString. Локализация основана на настройках языка устройства. Цену в виде числа можно получить через product.price?.amount — значение будет указано в местной валюте. Символ валюты доступен через product.price?.currencySymbol.
Subscription PeriodЧтобы отобразить период подписки (например, неделя, месяц, год и т. д.), используйте product.subscription?.localizedSubscriptionPeriod. Локализация основана на настройках языка устройства. Для программного получения периода подписки используйте product.subscription?.subscriptionPeriod. Через свойство unit можно узнать единицу периода: 'day', 'week', 'month', 'year' или 'unknown'. Свойство numberOfUnits возвращает количество единиц периода. Например, для квартальной подписки в unit будет 'month', а в numberOfUnits — 3.
Introductory OfferЧтобы показать бейдж или другой индикатор наличия introductory offer, проверьте свойство product.subscription?.offer?.phases. Это список, который может содержать до двух фаз скидки: фазу бесплатного пробного периода и фазу вводной цены. В каждом объекте фазы доступны следующие полезные свойства:
• paymentMode — строка со значениями 'free_trial', 'pay_as_you_go', 'pay_up_front' и 'unknown'. Бесплатные пробные периоды имеют тип 'free_trial'.
• price — сниженная цена в виде числа. Для бесплатных пробных периодов ожидайте значение 0.
• localizedNumberOfPeriods — локализованная строка, описывающая продолжительность предложения. Например, для трёхдневного пробного периода здесь будет '3 days'.
• subscriptionPeriod — позволяет получить отдельные параметры периода предложения. Работает так же, как описано в предыдущем разделе.
• localizedSubscriptionPeriod — форматированный период подписки для скидки в соответствии с языковыми настройками устройства.

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

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

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

Warning

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

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

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

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

try {
    const id = 'YOUR_PLACEMENT_ID';
    const locale = 'en';

    const paywall = await adapty.getPaywallForDefaultAudience(id, locale);
  // the requested paywall
} catch (error) {
    // handle the error
}
Note

Метод getPaywallForDefaultAudience доступен начиная с React Native SDK версии 2.11.2.

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

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

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

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

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

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

fetchPolicyпо умолчанию: 'reload_revalidating_cache_data'

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

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

Третья политика, 'return_cache_data_if_not_expired_else_load', находится между двумя предыдущими: она читает кеш, пока кешированная копия не старше значения maxAgeSeconds, переданного вместе с ней, и обращается к серверу, как только данные устаревают.

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