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

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

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

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

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

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

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

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

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

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

try {
    const placementId = 'YOUR_PLACEMENT_ID';

    const flow = await adapty.getFlow(placementId);
  // запрошенный флоу/пейвол
} catch (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 сек	Это значение ограничивает таймаут для данного метода. Если таймаут истекает, возвращаются кэшированные данные или локальный резервный вариант. Обратите внимание, что в редких случаях метод может завершиться с таймаутом чуть позже указанного в loadTimeout, поскольку операция может включать несколько запросов под капотом. Для Android: вы можете создать TimeInterval с помощью функций-расширений (например, 5.seconds, где .seconds — из import com.adapty.utils.seconds) или TimeInterval.seconds(5). Чтобы снять ограничение, используйте TimeInterval.INFINITE.

Response parameters:

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

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

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

В 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, которая ещё не выпущена. Пока билдер не поддерживает определение ID макетов, любое переданное значение не совпадёт ни с одним макетом и createFlowView выбросит AdaptyError. Оставьте поле неустановленным.
customTags	необязательный	Словарь пользовательских тегов и их значений, используемых как плейсхолдеры в контенте. Пользовательские теги применяются только к пейволам старого билдера — во флоу используются переменные.
prefetchProducts	необязательный	Включите для оптимизации времени отображения продуктов на экране. При значении true AdaptyUI автоматически загружает необходимые продукты. По умолчанию: false.
android.enableSafeArea	необязательный	Только для Android (игнорируется на iOS). Передаётся как вложенный объект: android: { enableSafeArea: true }. При значении true представление флоу применяет отступы безопасной зоны. По умолчанию 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. Если вы реализуете пейволы вручную, обратитесь к теме Получение пейволов и продуктов для пейволов с Remote Config в мобильном приложении.

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

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 и отдельный резервный сервер на случай недоступности CDN. Эта система гарантирует, что вы всегда получаете актуальную версию пейволов, обеспечивая надёжность даже при нестабильном интернете.
loadTimeoutMs	по умолчанию: 5 сек	Это значение ограничивает таймаут метода. При его истечении будут возвращены кэшированные данные или локальный резервный пейвол. Обратите внимание: в редких случаях метод может завершиться с небольшой задержкой относительно указанного в loadTimeout значения, поскольку операция может состоять из нескольких внутренних запросов. Для Android: вы можете создать TimeInterval с помощью функций-расширений (например, 5.seconds, где .seconds из import com.adapty.utils.seconds) или TimeInterval.seconds(5). Чтобы снять ограничение, используйте TimeInterval.INFINITE.

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

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

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

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

В 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 })