Получение флоу и пейволов - React Native

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

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

Прежде чем начать

Вам понадобится:

• Продукты в дашборде Adapty: Создайте продукты.
• Флоу с продуктами: Создайте его в Flow & Paywall Builder и привяжите к нему продукты.
• Плейсмент: Создайте плейсмент и назначьте ему флоу.
• Установленный SDK: Смотрите руководство по установке React Native SDK.

Получение флоу/пейвола

Если вы создали флоу или пейвол в билдере, вам не нужно беспокоиться о том, как отобразить его в коде мобильного приложения. Такой флоу или пейвол уже содержит и то, что должно быть показано, и то, как именно это должно выглядеть. Тем не менее, вам нужно получить его ID через плейсмент, конфигурацию представления, а затем отобразить его в мобильном приложении.

Получайте флоу или пейвол и создавайте его представление как можно раньше — в идеале задолго до того, как вы его покажете. Метод createFlowView загружает конфигурацию представления и в фоновом режиме начинает скачивать и кешировать изображения. Чем раньше вы его вызовете, тем больше времени будет на завершение загрузки. К моменту показа флоу или пейвола его конфигурация и изображения уже могут быть в кеше и готовы к отображению.

Чтобы получить флоу или пейвол, используйте метод getFlow:

try {
    const placementId = 'YOUR_PLACEMENT_ID';

    const flow = await adapty.getFlow(placementId);
  // the requested flow/paywall
} 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, поскольку операция может включать несколько последовательных запросов.

Response parameters:

Parameter	Description
Flow	Объект AdaptyFlow с идентификаторами флоу (id, variationId), названием варианта (variationName, необязательно, SDK 4.2+), именем, плейсментом, вариантами пейволов (paywalls), любыми Remote Config (remoteConfigs), а также — начиная с SDK 4.1 — флагом hasViewConfiguration.

Получение конфигурации отображения

Если плейсмент создан в Flow & Paywall Builder или в old Paywall Builder, Adapty отрисует UI за вас. Создайте отображение с помощью createFlowView, затем покажите флоу или пейвол. Если плейсмент — это кастомный пейвол без UI в Builder, отрисуйте его самостоятельно.

В SDK 4.1 и выше флаг hasViewConfiguration на объекте флоу позволяет отличить один случай от другого ещё до создания представления:

if (flow.hasViewConfiguration) {
  const view = await createFlowView(flow);
  await view.present();
} else {
  // Render your own screen from flow.remoteConfigs and flow.paywalls
}

В версии 4.0 этот флаг отсутствует, и createFlowView выбрасывает AdaptyError для флоу без конфигурации представления.

В React Native SDK вызывайте createFlowView напрямую — предварительно получать конфигурацию представления не нужно.

try {
  const view = await createFlowView(flow);
} catch (error) {
  // handle the error
}

Параметры:

Параметр	Наличие	Описание
flow	обязательный	Объект AdaptyFlow для получения контроллера нужного флоу/пейвола.
locale	необязательный	Идентификатор локализации флоу для отображения — например, en или pt-br. Если не задан, используется en или локализация флоу по умолчанию (если en отсутствует). Требуется SDK 4.0.2 или выше. См. Локализации и коды языков.
customLayoutId	необязательный по умолчанию: undefined SDK 4.1+	Зарезервировано для возможности Flow & Paywall Builder, которая ещё не выпущена. Пока билдер не поддерживает идентификаторы макетов, любое переданное значение не будет соответствовать ни одному макету, и createFlowView вернёт ошибку AdaptyError. Оставьте параметр незаданным.
customTags	необязательный	Значения приложения для пользовательских тегов флоу в виде объекта, где ключи — полные имена тегов. Подробнее: Передача данных во флоу.
prefetchProducts	необязательный	Включите для оптимизации времени отображения продуктов на экране. При значении true AdaptyUI автоматически загрузит необходимые продукты. По умолчанию: false.
android.enableSafeArea	необязательный	Только для Android (игнорируется на iOS). Передаётся как вложенный объект: android: { enableSafeArea: true }. При значении true отображение флоу учитывает отступы safe area. По умолчанию true при модальном отображении (createFlowView + present()) и false для встроенного компонента AdaptyFlowView. Значение по умолчанию подходит для большинства случаев.

Когда у вас есть представление, откройте флоу/пейвол.

Получение флоу или пейвола для аудитории по умолчанию для более быстрой загрузки

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

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

try {
    const id = 'YOUR_PLACEMENT_ID';

    const flow = await adapty.getFlowForDefaultAudience(id);
  // the requested flow/paywall
} 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, переданное вместе с ней, и обращается к серверу, как только кэш устаревает. Обратите внимание, что кэш сохраняется при перезапуске приложения и очищается только при его переустановке или принудительной очистке вручную.

Настройка ассетов

Чтобы настроить изображения и видео во флоу или пейволе, реализуйте кастомные ассеты.

Фоновые изображения и видео имеют предопределённые идентификаторы: hero_image и hero_video. В бандле кастомных ассетов вы обращаетесь к этим элементам по их идентификаторам и настраиваете их поведение.

Для остальных изображений и видео нужно задать кастомный идентификатор в дашборде Adapty.

Например, вы можете:

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

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

const customAssets: Record<string, AdaptyCustomAsset> = {
  'custom_image': { type: 'image', relativeAssetPath: 'custom_image.png' },
  'hero_video': {
    type: 'video',
    fileLocation: {
      ios: { fileName: 'custom_video.mp4' },
      android: { relativeAssetPath: 'videos/custom_video.mp4' }
    }
  }
};

view = await createFlowView(flow, { customAssets })

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

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

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

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

Получение пейвола, созданного в Paywall Builder

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

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

Для получения пейвола используйте метод getPaywall:

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

    const paywall = await adapty.getPaywall(placementId, 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, а при его недоступности — отдельный резервный сервер. Такая система обеспечивает получение актуальной версии пейволов при сохранении надёжности даже при нестабильном интернет-соединении.
loadTimeoutMs	по умолчанию: 5 сек	Это значение ограничивает таймаут метода. Если сервер Adapty не отвечает вовремя или возвращает ошибку, SDK возвращает пейвол с резервного сервера (копия CDN, обслуживающая только аудиторию All Users плейсмента), из кэша или из вашего резервного файла. Обратите внимание: в редких случаях таймаут метода может наступить немного позже указанного в loadTimeout, так как операция может включать несколько запросов под капотом.

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

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

Получение конфигурации представления пейвола, созданного в Paywall Builder

После получения пейвола проверьте, содержит ли он ViewConfiguration — это означает, что пейвол был создан в Paywall Builder. Это поможет вам определить, как отображать пейвол. Если ViewConfiguration присутствует, обрабатывайте его как пейвол Paywall Builder; если нет — обработайте его как кастомный пейвол.

В React Native SDK напрямую вызывайте метод createPaywallView, не извлекая конфигурацию представления вручную.

// for the Adapty SDK < 3.14 – import {createPaywallView} from 'react-native-adapty/dist/ui';

if (paywall.hasViewConfiguration) {
  try {
    const view = await createPaywallView(paywall);
  } catch (error) {
    // handle the error
  }
} else {
    //use your custom logic
}

Параметры:

Параметр	Обязательность	Описание
paywall	обязательный	Объект AdaptyPaywall для получения контроллера нужного пейвола.
customTags	необязательный	Словарь пользовательских тегов и их значений. Пользовательские теги служат плейсхолдерами в содержимом пейвола и динамически заменяются конкретными строками для персонализации контента. Подробнее см. в разделе о пользовательских тегах в Paywall Builder.
prefetchProducts	необязательный	Включите для оптимизации времени отображения продуктов на экране. При значении true AdaptyUI автоматически загрузит необходимые продукты. По умолчанию: false.

После того как у вас есть представление, отобразите пейвол.

Получите пейвол для аудитории по умолчанию, чтобы загрузить его быстрее

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

Чтобы решить эту задачу, используйте метод getPaywallForDefaultAudience, который получает пейвол указанного плейсмента для аудитории All Users. Однако важно понимать, что рекомендуемый подход — получать пейвол через метод 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
}

Параметр	Наличие	Описание
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, переданного вместе с ней, и обращается к серверу, как только кэш устаревает. Обратите внимание: кэш сохраняется при перезапуске приложения и очищается только при его переустановке или ручной очистке.

Настройка ресурсов

Чтобы настроить изображения и видео на пейволе, используйте пользовательские ресурсы.

У hero-изображений и видео есть предопределённые идентификаторы: hero_image и hero_video. В бандле пользовательских ресурсов вы обращаетесь к этим элементам по их идентификаторам и настраиваете их поведение.

Для остальных изображений и видео необходимо задать пользовательский идентификатор в дашборде Adapty.

Например, вы можете:

• Показывать разные изображения или видео разным пользователям.
• Показывать локальное превью-изображение, пока загружается основное удалённое изображение.
• Показывать превью-изображение перед запуском видео.

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

const customAssets: Record<string, AdaptyCustomAsset> = {
  'custom_image': { type: 'image', relativeAssetPath: 'custom_image.png' },
  'hero_video': {
    type: 'video',
    fileLocation: {
      ios: { fileName: 'custom_video.mp4' },
      android: { relativeAssetPath: 'videos/custom_video.mp4' }
    }
  }
};

view = await createPaywallView(paywall, { customAssets })