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

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

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

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

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

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

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

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

Adapty.getFlow(
    placementId = "YOUR_PLACEMENT_ID",
    fetchPolicy = AdaptyPaywallFetchPolicy.Default,
    loadTimeout = 5.seconds
).onSuccess { flow ->
    // запрошенный флоу/пейвол
}.onError { error ->
    // обработка ошибки
}

Параметры:

Параметр	Наличие	Описание
placementId	обязательный	Идентификатор нужного плейсмента. Это значение вы указали при создании плейсмента в дашборде Adapty.
fetchPolicy	по умолчанию: AdaptyPaywallFetchPolicy.Default	По умолчанию SDK пытается загрузить данные с сервера и возвращает кешированные данные в случае сбоя. Мы рекомендуем этот вариант, так как он гарантирует, что пользователи всегда получают самые актуальные данные. Однако если у ваших пользователей нестабильный интернет, рассмотрите использование AdaptyPaywallFetchPolicy.ReturnCacheDataElseLoad для возврата кешированных данных, если они есть. В этом случае пользователи могут не получить самые последние данные, но загрузка будет быстрее вне зависимости от качества соединения. Кеш регулярно обновляется, поэтому его безопасно использовать в течение сессии во избежание лишних сетевых запросов. Обратите внимание, что кеш сохраняется после перезапуска приложения и очищается только при переустановке или ручной очистке. Adapty SDK хранит флоу и пейволы локально в двух слоях: регулярно обновляемый кеш, описанный выше, и резервные пейволы. Для более быстрой загрузки используется CDN, а также отдельный резервный сервер на случай недоступности CDN. Эта система гарантирует получение последней версии данных и надёжную работу даже при слабом интернете.
loadTimeout	по умолчанию: 5 сек	Это значение ограничивает таймаут метода. При его истечении будут возвращены кешированные данные или локальный резервный пейвол. Обратите внимание, что в редких случаях метод может завершиться чуть позже указанного в loadTimeout значения, поскольку операция может включать несколько запросов под капотом. Для Kotlin Multiplatform: вы можете создать Duration с помощью функций-расширений, например 5.seconds, где .seconds — из kotlin.time.Duration.Companion.seconds.

Параметр	Описание
Flow	Объект AdaptyFlow, содержащий плейсмент, идентификаторы (instanceIdentity, variationId), название, варианты пейвола (paywalls — список AdaptyFlowPaywall) и Remote Config (remoteConfigs — список с одной записью на каждую локаль). Чтобы получить продукты для предзагрузки, кастомного UI или программных проверок, вызовите getPaywallProducts(flow).

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

После получения флоу или пейвола загрузите конфигурацию представления и создайте само представление за один шаг с помощью метода createFlowView. Отдельного флага для проверки нет: если плейсмент был создан в Flow Builder (флоу) или Paywall Builder (пейвол), createFlowView возвращает представление, готовое к показу. Если плейсмент — это кастомный пейвол без UI в Builder, createFlowView возвращает AdaptyResult.Error — обработайте его как пейвол с Remote Config.

AdaptyUI.createFlowView(
    flow = flow,
    loadTimeout = 5.seconds,
    preloadProducts = true
).onSuccess { view ->
    // use view
}.onError { error ->
    // the flow has no view configured, or view creation failed
}

Параметр	Наличие	Описание
flow	обязательный	Объект AdaptyFlow, полученный через Adapty.getFlow.
loadTimeout	необязательный	Ограничивает тайм-аут для этого метода. Если тайм-аут истёк, будут возвращены кэшированные данные или локальный резервный вариант. Обратите внимание, что в редких случаях метод может завершиться с тайм-аутом чуть позже указанного в loadTimeout, поскольку операция может включать несколько запросов под капотом. Можно использовать функции-расширения вроде 5.seconds из kotlin.time.Duration.Companion.
preloadProducts	необязательный	Установите true, чтобы заранее загрузить продукты для повышения производительности. При включении продукты загружаются заблаговременно, сокращая время отображения флоу или пейвола.
productPurchaseParams	необязательный	Карта AdaptyProductIdentifier к AdaptyPurchaseParameters. Используйте её для настройки параметров покупки — например, персонализированных предложений или параметров обновления подписки для отдельных продуктов во флоу или пейволе.

После загрузки отобразите флоу или пейвол.

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

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

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

Adapty.getFlowForDefaultAudience(
    placementId = "YOUR_PLACEMENT_ID",
    fetchPolicy = AdaptyPaywallFetchPolicy.Default,
).onSuccess { flow ->
    // the requested flow
}.onError { error ->
    // handle the error
}

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

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

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

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

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

Например, можно:

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

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

// Import generated Res class for accessing resources

viewModelScope.launch {
    // Get URIs for bundled resources using Res.getUri()
    val heroImagePath = Res.getUri("files/images/hero_image.png")
    val demoVideoPath = Res.getUri("files/videos/demo_video.mp4")

    // Or read image as byte data
    val imageByteData = Res.readBytes("files/images/avatar.png")

    // Create custom assets map
    val customAssets: Map<String, AdaptyCustomAsset> = mapOf(
        // Load image from app resources (bundled with the app)
        // Files should be placed in commonMain/composeResources/files/
        "hero_image" to AdaptyCustomAsset.localImageResource(
            path = heroImagePath
        ),

        // Or use image byte data
        "avatar" to AdaptyCustomAsset.localImageData(
            data = imageByteData
        ),

        // Load video from app resources
        "demo_video" to AdaptyCustomAsset.localVideoResource(
            path = demoVideoPath
        ),

        // Or use a video file from device storage
        "intro_video" to AdaptyCustomAsset.localVideoFile(
            path = "/path/to/local/video.mp4"
        ),

        // Apply custom brand colors
        "brand_primary" to AdaptyCustomAsset.color(
            colorHex = "#FF6B35"
        ),

        // Create gradient background
        "card_gradient" to AdaptyCustomAsset.linearGradient(
            colors = listOf("#1E3A8A", "#3B82F6", "#60A5FA"),
            stops = listOf(0.0f, 0.5f, 1.0f)
        )
    )

    // Use custom assets when creating the flow view
    AdaptyUI.createFlowView(
        flow = flow,
        customAssets = customAssets
    ).onSuccess { view ->
        // Present the flow with custom assets
        view.present()
    }.onError { error ->
        // Handle the error - the flow will fall back to default appearance
    }
}

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

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

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

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

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

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

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

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

Adapty.getPaywall(
    placementId = "YOUR_PLACEMENT_ID",
    locale = "en",
    fetchPolicy = AdaptyPaywallFetchPolicy.Default,
    loadTimeout = 5.seconds
).onSuccess { paywall ->
    // the requested paywall
}.onError { error ->
    // handle the error
}

Параметры:

Параметр	Наличие	Описание
placementId	обязательный	Идентификатор нужного плейсмента. Это значение вы указываете при создании плейсмента в дашборде Adapty.
locale	опциональный по умолчанию: en	Идентификатор локализации пейвола. Ожидается языковой код, состоящий из одного или двух субтегов, разделённых дефисом (-). Первый субтег — язык, второй — регион. Пример: en — английский, pt-br — бразильский португальский. Подробнее о кодах локализации и рекомендациях по их использованию см. в разделе Локализации и коды локалей.
fetchPolicy	по умолчанию: AdaptyPaywallFetchPolicy.Default	По умолчанию SDK пытается загрузить данные с сервера и возвращает кешированные данные в случае ошибки. Мы рекомендуем этот вариант, так как он гарантирует, что пользователи всегда получают актуальные данные. Однако если у ваших пользователей нестабильное интернет-соединение, рассмотрите использование AdaptyPaywallFetchPolicy.ReturnCacheDataElseLoad — оно вернёт кешированные данные, если они есть. В этом случае пользователи могут не получить самые последние данные, зато загрузка будет быстрее вне зависимости от качества соединения. Кеш регулярно обновляется, поэтому его безопасно использовать в рамках сессии, чтобы сократить количество сетевых запросов. Обратите внимание: кеш сохраняется при перезапуске приложения и очищается только при его переустановке или вручную. Adapty SDK хранит пейволы локально в двух слоях: описанный выше регулярно обновляемый кеш и резервные пейволы. Мы также используем CDN для ускоренной загрузки пейволов и отдельный резервный сервер на случай недоступности CDN. Эта система гарантирует, что вы всегда получаете актуальную версию пейволов, обеспечивая надёжность даже при слабом интернет-соединении.
loadTimeout	по умолчанию: 5 сек	Это значение ограничивает таймаут для данного метода. При достижении таймаута будут возвращены кешированные данные или локальный резервный вариант. Обратите внимание: в редких случаях метод может завершиться с небольшим опозданием относительно значения loadTimeout, поскольку операция может включать несколько запросов внутри. Для Kotlin Multiplatform: 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.

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

if (paywall.hasViewConfiguration) {
    AdaptyUI.createPaywallView(
        paywall = paywall,
        loadTimeout = 5.seconds,
        preloadProducts = true
    ).onSuccess { paywallView ->
        // use paywallView
    }.onError { error ->
        // handle the error
    }
} else {
    // use your custom logic
}

Parameter	Presence	Description
paywall	required	Объект AdaptyPaywall для получения контроллера нужного пейвола.
loadTimeout	optional	Ограничивает таймаут для этого метода. Если таймаут истекает, возвращаются кешированные данные или локальный резервный вариант. Обратите внимание, что в редких случаях метод может завершиться чуть позже указанного в loadTimeout значения, поскольку операция может состоять из нескольких запросов. Можно использовать функции-расширения, например 5.seconds из kotlin.time.Duration.Companion.
preloadProducts	optional	Установите true, чтобы заранее загрузить продукты для повышения производительности. При включении продукты загружаются заблаговременно, сокращая время отображения пейвола.
productPurchaseParams	optional	Словарь, сопоставляющий AdaptyProductIdentifier с AdaptyPurchaseParameters. Используйте его для настройки параметров покупки — например, персонализированных офферов или параметров обновления подписки для отдельных продуктов пейвола.

После загрузки откройте пейвол.

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

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

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

Adapty.getPaywallForDefaultAudience(
    placementId = "YOUR_PLACEMENT_ID",
    locale = "en",
    fetchPolicy = AdaptyPaywallFetchPolicy.Default,
).onSuccess { paywall ->
    // the requested paywall
}.onError { error ->
    // handle the error
}

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

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

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

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

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

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

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

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

// Import generated Res class for accessing resources

viewModelScope.launch {
    // Get URIs for bundled resources using Res.getUri()
    val heroImagePath = Res.getUri("files/images/hero_image.png")
    val demoVideoPath = Res.getUri("files/videos/demo_video.mp4")

    // Or read image as byte data
    val imageByteData = Res.readBytes("files/images/avatar.png")

    // Create custom assets map
    val customAssets: Map<String, AdaptyCustomAsset> = mapOf(
        // Load image from app resources (bundled with the app)
        // Files should be placed in commonMain/composeResources/files/
        "hero_image" to AdaptyCustomAsset.localImageResource(
            path = heroImagePath
        ),

        // Or use image byte data
        "avatar" to AdaptyCustomAsset.localImageData(
            data = imageByteData
        ),

        // Load video from app resources
        "demo_video" to AdaptyCustomAsset.localVideoResource(
            path = demoVideoPath
        ),

        // Or use a video file from device storage
        "intro_video" to AdaptyCustomAsset.localVideoFile(
            path = "/path/to/local/video.mp4"
        ),

        // Apply custom brand colors
        "brand_primary" to AdaptyCustomAsset.color(
            colorHex = "#FF6B35"
        ),

        // Create gradient background
        "card_gradient" to AdaptyCustomAsset.linearGradient(
            colors = listOf("#1E3A8A", "#3B82F6", "#60A5FA"),
            stops = listOf(0.0f, 0.5f, 1.0f)
        )
    )

    // Use custom assets when creating paywall view
    AdaptyUI.createPaywallView(
        paywall = paywall,
        customAssets = customAssets
    ).onSuccess { paywallView ->
        // Present the paywall with custom assets
        paywallView.present()
    }.onError { error ->
        // Handle the error - paywall will fall back to default appearance
    }
}