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

Response parameters:

Параметр	Описание
Flow	Объект AdaptyFlow с идентификаторами флоу (id, variationId), именем, плейсментом, вариантами пейволов (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	по умолчанию: .reloadRevalidatingCacheData	По умолчанию SDK пытается загрузить данные с сервера и возвращает кешированные данные в случае ошибки. Мы рекомендуем этот вариант, так как он гарантирует, что пользователи всегда получают самые актуальные данные. Однако если у ваших пользователей нестабильное интернет-соединение, рассмотрите использование .returnCacheDataElseLoad — оно вернёт кешированные данные, если они есть. В этом случае пользователи могут получить не самые свежие данные, зато загрузка будет быстрее вне зависимости от качества связи. Кеш регулярно обновляется, поэтому его безопасно использовать в течение сессии, чтобы сократить количество сетевых запросов. Обратите внимание: кеш сохраняется при перезапуске приложения и очищается только при его переустановке или принудительной очистке вручную.

Кастомизация ресурсов

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

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

Для остальных изображений и видео нужно задать пользовательский ID в дашборде 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	по умолчанию: .reloadRevalidatingCacheData	По умолчанию SDK пытается загрузить данные с сервера и возвращает кешированные данные в случае ошибки. Мы рекомендуем этот вариант, поскольку он гарантирует, что пользователи всегда получают самые актуальные данные. Однако если у ваших пользователей нестабильное интернет-соединение, рассмотрите использование .returnCacheDataElseLoad, чтобы возвращать кешированные данные при их наличии. В этом случае пользователи могут получить не самые свежие данные, зато загрузка будет быстрее вне зависимости от качества соединения. Кеш регулярно обновляется, поэтому его безопасно использовать в течение сессии, чтобы избежать лишних сетевых запросов. Обратите внимание: кеш сохраняется при перезапуске приложения и очищается только при его переустановке или вручную. 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	по умолчанию: .reloadRevalidatingCacheData	По умолчанию SDK пытается загрузить данные с сервера и возвращает кешированные данные в случае ошибки. Мы рекомендуем этот вариант, поскольку он гарантирует, что пользователи всегда получают актуальные данные. Однако если у ваших пользователей нестабильное интернет-соединение, рассмотрите вариант .returnCacheDataElseLoad — он возвращает кешированные данные, если они есть. В таком случае пользователи могут получить не самые свежие данные, зато загрузка будет быстрее вне зависимости от качества соединения. Кеш регулярно обновляется, поэтому его безопасно использовать в течение сессии, чтобы избежать лишних сетевых запросов. Обратите внимание: кеш сохраняется при перезапуске приложения и очищается только при его переустановке или вручную.

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

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

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