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

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

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

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

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

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

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

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

try {
  const flow = await adapty.getFlow({
    placementId: 'YOUR_PLACEMENT_ID',
  });
  // запрошенный флоу/пейвол
} catch (error) {
  // обработка ошибки
}

Параметры:

Параметр	Наличие	Описание
placementId	обязательный	Идентификатор нужного плейсмента. Это значение вы указали при создании плейсмента в дашборде Adapty.
fetchPolicy	по умолчанию: 'reload_revalidating_cache_data'	Передаётся внутри опционального объекта params. По умолчанию SDK пытается загрузить данные с сервера и возвращает кешированные данные в случае сбоя. Рекомендуем этот вариант, поскольку он гарантирует, что пользователи всегда получают самые актуальные данные. Однако если вы считаете, что у ваших пользователей нестабильный интернет, рассмотрите использование 'return_cache_data_else_load' — тогда кеш будет возвращаться, если он существует. В этом случае пользователи могут не получить самые последние данные, зато загрузка будет быстрее вне зависимости от качества соединения. Кеш регулярно обновляется, поэтому его безопасно использовать в течение сессии во избежание лишних сетевых запросов. Обратите внимание: кеш сохраняется при перезапуске приложения и очищается только при переустановке или вручную. Adapty SDK хранит пейволы локально в двух слоях: регулярно обновляемый кеш, описанный выше, и резервные пейволы. Для более быстрой загрузки пейволов также используется CDN, а при недоступности CDN — отдельный резервный сервер. Такая система гарантирует, что вы всегда получаете актуальную версию пейволов, обеспечивая надёжность даже при слабом интернет-соединении.
loadTimeoutMs	по умолчанию: 5 сек	Передаётся внутри опционального объекта params. Это значение ограничивает тайм-аут данного метода. По истечении тайм-аута будут возвращены кешированные данные или локальный резервный вариант. Обратите внимание: в редких случаях метод может завершиться с небольшой задержкой относительно значения, указанного в loadTimeoutMs, поскольку операция может включать несколько запросов под капотом.
Не хардкодьте идентификаторы продуктов. Единственный ID, который стоит хардкодить, — это ID плейсмента. Флоу и пейволы настраиваются удалённо, поэтому количество продуктов и доступных офферов может меняться в любой момент. Ваше приложение должно обрабатывать эти изменения динамически: если сегодня пейвол возвращает два продукта, а завтра три — отображайте все без изменений в коде.

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

Параметр	Описание
Flow	Объект AdaptyFlow с идентификаторами флоу (id, variationId), названием, плейсментом, вариантами пейволов (paywalls) и Remote Config (remoteConfigs).

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

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

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

Параметры:

Параметр	Наличие	Описание
flow	обязательный	Объект AdaptyFlow для получения контроллера нужного флоу/пейвола.
customTags	необязательный	Словарь пользовательских тегов и их значений. Теги служат плейсхолдерами в контенте и динамически заменяются конкретными строками для персонализации контента во флоу/пейволе. Подробнее см. в разделе о пользовательских тегах в Paywall Builder.
prefetchProducts	необязательный	Включите для оптимизации времени отображения продуктов на экране. При значении true AdaptyUI автоматически загружает нужные продукты. По умолчанию: true.
android.enableSafeArea	необязательный	Только для Android (игнорируется на iOS). Указывается в ключе android. При значении true представление флоу применяет отступы безопасной зоны. По умолчанию: true. Значение по умолчанию подходит для большинства случаев.

Когда вью готово, отобразите флоу/пейвол.

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

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

try {
  const flow = await adapty.getFlowForDefaultAudience({
    placementId: 'YOUR_PLACEMENT_ID',
  });
  // the requested flow/paywall
} catch (error) {
  // handle the error
}

Параметр	Наличие	Описание
placementId	обязательный	Идентификатор плейсмента. Это значение вы указали при создании плейсмента в дашборде Adapty.
fetchPolicy	по умолчанию: 'reload_revalidating_cache_data'	Передаётся внутри необязательного объекта params. По умолчанию SDK пытается загрузить данные с сервера и возвращает кешированные данные в случае ошибки. Мы рекомендуем этот вариант, поскольку он гарантирует, что пользователи всегда получают актуальные данные. Однако если у ваших пользователей нестабильное интернет-соединение, рассмотрите вариант 'return_cache_data_else_load' — он возвращает кешированные данные, если они есть. В этом случае пользователи могут получить не самые последние данные, зато загрузка будет быстрее вне зависимости от качества связи. Кеш регулярно обновляется, поэтому его безопасно использовать в течение сессии для снижения количества сетевых запросов. Обратите внимание: кеш сохраняется при перезапуске приложения и очищается только при переустановке или вручную.

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

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

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' }
    }
  }
};

const view = await createFlowView(flow, { customAssets });

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

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

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

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

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

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

try {
  const paywall = await adapty.getPaywall({
    placementId: 'YOUR_PLACEMENT_ID',
    locale: 'en',
  });
  // the requested paywall
} catch (error) {
  // handle the error
}

Параметры:

Параметр	Наличие	Описание
placementId	обязательный	Идентификатор нужного плейсмента. Это значение вы указываете при создании плейсмента в дашборде Adapty.
locale	необязательный по умолчанию: en	Идентификатор локализации пейвола. Ожидается, что этот параметр будет представлять собой код языка из одного или двух подтегов, разделённых символом минус (-). Первый подтег обозначает язык, второй — регион. Пример: en означает английский, pt-br — бразильский португальский. Подробнее о кодах локализации и рекомендациях по их использованию см. в разделе Локализации и коды локалей.
params	необязательный	Дополнительные параметры для получения пейвола.
Не хардкодьте идентификаторы продуктов. Единственный ID, который стоит хардкодить — это ID плейсмента. Пейволы настраиваются удалённо, поэтому количество продуктов и доступных офферов может меняться в любой момент. Ваше приложение должно обрабатывать эти изменения динамически: если сегодня пейвол возвращает два продукта, а завтра три — отображайте все без изменений в коде.

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

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

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

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

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

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 paywall = await adapty.getPaywallForDefaultAudience({
    placementId: 'YOUR_PLACEMENT_ID',
    locale: 'en',
  });
  // the requested paywall
} catch (error) {
  // handle the error
}

Параметр	Обязательность	Описание
placementId	обязательный	Идентификатор плейсмента. Это значение вы указали при создании плейсмента в дашборде Adapty.
locale	необязательный по умолчанию: en	Идентификатор локализации пейвола. Ожидается языковой код, состоящий из одного или нескольких подтегов, разделённых символом «минус» (-). Первый подтег — язык, второй — регион. Пример: en — английский, pt-br — бразильский португальский. Подробнее о кодах локалей и рекомендациях по их использованию см. в разделе Локализации и коды локалей.
params	необязательный	Дополнительные параметры для получения пейвола.

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

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

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