Отображение флоу и пейволов - Kotlin Multiplatform

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

Этот гайд охватывает флоу и пейволы нового Paywall Builder, которые отрисовывает Adapty. Для Remote Config пейволов и режима Observer mode процесс отличается.

Для отображения пейволов с Remote Config см. Отображение пейволов на основе Remote Config.
Для отображения флоу в режиме Observer, см. Отображение флоу в режиме Observer.

Чтобы получить объект flow, используемый далее, см. Получение флоу и пейволов.

Adapty Kotlin Multiplatform SDK предоставляет два способа отображения флоу и пейволов:

С Compose Multiplatform
Без Compose Multiplatform

С Compose Multiplatform

Чтобы отобразить флоу или пейвол, используйте метод view.present() на объекте view, созданном методом createFlowView. Каждый view можно использовать только один раз. Если нужно отобразить флоу повторно, вызовите createFlowView ещё раз, чтобы создать новый экземпляр view.

Повторное использование одного и того же view без его пересоздания может привести к ошибке.


viewModelScope.launch {
    AdaptyUI.createFlowView(flow = flow).onSuccess { view ->
        view.present()
    }.onError { error ->
        // handle the error
    }
}

Показ диалога

Используйте этот метод вместо нативных диалоговых окон alert, когда флоу или пейвол отображается на Android. На Android обычные alert появляются позади слоя флоу, что делает их невидимыми для пользователей. Этот метод обеспечивает корректное отображение диалога поверх флоу на всех платформах.


viewModelScope.launch {
    view.showDialog(
        title = "Close this screen?",
        content = "You will lose access to exclusive offers.",
        primaryActionTitle = "Stay",
        secondaryActionTitle = "Close"
    ).onSuccess { action ->
        if (action == AdaptyUIDialogActionType.SECONDARY) {
            // User confirmed - close the flow
            view.dismiss()
        }
        // If primary - do nothing, user stays
    }.onError { error ->
        // handle the error
    }
}

Настройка стиля отображения на iOS

Настройте способ отображения флоу или пейвола на iOS, передав параметр iosPresentationStyle в метод present(). Параметр принимает значения AdaptyUIIOSPresentationStyle.FULLSCREEN (по умолчанию) или AdaptyUIIOSPresentationStyle.PAGESHEET.


viewModelScope.launch {
    val view = AdaptyUI.createFlowView(flow = flow).getOrNull()
    view?.present(iosPresentationStyle = AdaptyUIIOSPresentationStyle.PAGESHEET)
}

Без Compose Multiplatform

createNativeFlowView является частью основного модуля io.adapty:adapty-kmp. Если ваш проект не использует Compose Multiplatform, зависимость io.adapty:adapty-kmp-ui вам не нужна.

Чтобы встроить флоу или пейвол без Compose Multiplatform, вызовите createNativeFlowView. Метод возвращает AdaptyNativeFlowView, который нужно добавить в ваш лейаут:


val nativeView = AdaptyUI.createNativeFlowView(
    context = context,
    viewModelStoreOwner = activity,
    flow = flow,
    observer = myFlowObserver,
)

// Embed in your Compose layout:
AndroidView(
    factory = { nativeView.view },
    modifier = Modifier.fillMaxSize()
)

По умолчанию встроенное представление не применяет отступы безопасной зоны — ваш макет должен самостоятельно обрабатывать вставки. Если вы хотите, чтобы представление применяло их само, передайте androidEnableSafeArea = true в createNativeFlowView. Этот параметр доступен только для Android.

Поскольку методы по умолчанию интерфейса KMP становятся @required в Swift, вы не можете реализовать AdaptyUIFlowsEventsObserver напрямую из Swift. Сначала объявите открытый базовый класс в iosMain:

open class BaseFlowObserver : AdaptyUIFlowsEventsObserver

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

class MyFlowObserver: BaseFlowObserver {
    override func flowViewDidPerformAction(view: AdaptyUIFlowView, action: any AdaptyUIAction) {
        if action is AdaptyUIActionCloseAction {
            // remove nativeView from your view hierarchy
        }
    }
}

let nativeView = AdaptyUI.shared.createNativeFlowView(
    flow: flow,
    observer: MyFlowObserver()
)
// nativeView.viewController is a UIViewController.
// Add it to your SwiftUI view or UIKit hierarchy.

Освобождение ресурсов представления

Вызовите dispose() при удалении представления из макета. Это снимает регистрацию слушателя событий и освобождает внутренние ресурсы.

nativeView.dispose()

Кастомные теги

Кастомные теги позволяют не создавать отдельные флоу или пейволы для разных сценариев. Представьте один флоу, который динамически адаптируется под данные пользователя. Например, вместо безликого «Привет!» можно приветствовать пользователей лично: «Привет, Иван!» или «Привет, Анна!»

Вот несколько примеров использования кастомных тегов:

Отображать имя или email пользователя на флоу или пейволе.
Показывать текущий день недели для стимулирования продаж (например, «С четвергом!»).
Добавлять персонализированные детали о продаваемых продуктах (например, название фитнес-программы или номер телефона в VoIP-приложении).

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

В некоторых случаях приложение может не знать, чем заменить пользовательский тег — особенно если пользователи работают на старой версии AdaptyUI SDK. Чтобы избежать этого, всегда добавляйте резервный текст, который будет подставляться вместо строк с неизвестными тегами. Без этого пользователи могут видеть теги в виде кода (<USERNAME/>).

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


viewModelScope.launch {
    val customTags = mapOf(
        "USERNAME" to "John",
        "DAY_OF_WEEK" to "Thursday"
    )

    AdaptyUI.createFlowView(
        flow = flow,
        customTags = customTags
    ).onSuccess { view ->
        view.present()
    }.onError { error ->
        // handle the error
    }
}


val customTags = mapOf(
    "USERNAME" to "John",
    "DAY_OF_WEEK" to "Thursday"
)

val nativeView = AdaptyUI.createNativeFlowView(
    context = context,
    viewModelStoreOwner = activity,
    flow = flow,
    observer = myFlowObserver,
    customTags = customTags,
)


val customTags = mapOf(
    "USERNAME" to "John",
    "DAY_OF_WEEK" to "Thursday"
)

val nativeView = AdaptyUI.createNativeFlowView(
    flow = flow,
    observer = myFlowObserver,
    customTags = customTags,
)

Пользовательские таймеры

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

Вы можете настроить текст до и после таймера, чтобы сформировать нужное сообщение, например: «Предложение заканчивается через: 10:00 сек.»

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


viewModelScope.launch {
    val customTimers = mapOf(
        "CUSTOM_TIMER_NY" to LocalDateTime(2025, 1, 1, 0, 0, 0),
        "CUSTOM_TIMER_SALE" to LocalDateTime(2024, 12, 31, 23, 59, 59)
    )

    AdaptyUI.createFlowView(
        flow = flow,
        customTimers = customTimers
    ).onSuccess { view ->
        view.present()
    }.onError { error ->
        // handle the error
    }
}


val customTimers = mapOf(
    "CUSTOM_TIMER_NY" to LocalDateTime(2025, 1, 1, 0, 0, 0),
    "CUSTOM_TIMER_SALE" to LocalDateTime(2024, 12, 31, 23, 59, 59)
)

val nativeView = AdaptyUI.createNativeFlowView(
    context = context,
    viewModelStoreOwner = activity,
    flow = flow,
    observer = myFlowObserver,
    customTimers = customTimers,
)


val customTimers = mapOf(
    "CUSTOM_TIMER_NY" to LocalDateTime(2025, 1, 1, 0, 0, 0),
    "CUSTOM_TIMER_SALE" to LocalDateTime(2024, 12, 31, 23, 59, 59)
)

val nativeView = AdaptyUI.createNativeFlowView(
    flow = flow,
    observer = myFlowObserver,
    customTimers = customTimers,
)

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

Этот гайд предназначен только для пейволов, созданных с помощью нового Paywall Builder. Процесс отображения пейволов отличается для пейволов на основе Remote Config и режима Observer.

Для отображения пейволов на основе Remote Config см. Рендеринг пейвола, созданного с помощью Remote Config.

SDK Adapty Kotlin Multiplatform предоставляет два способа отображения пейволов:

С Compose Multiplatform
Без Compose Multiplatform

С Compose Multiplatform

Чтобы отобразить пейвол, вызовите метод view.present() на объекте view, созданном методом createPaywallView. Каждый объект view можно использовать только один раз. Если нужно показать пейвол повторно, вызовите createPaywallView ещё раз, чтобы создать новый экземпляр view.

Повторное использование одного и того же view без его пересоздания может привести к ошибке.


viewModelScope.launch {
    AdaptyUI.createPaywallView(paywall = paywall).onSuccess { view ->
        view.present()
    }.onError { error ->
        // handle the error
    }
}

Показ диалогов

Используйте этот метод вместо нативных диалогов alert, когда на Android отображается пейвол. На Android стандартные алерты появляются позади пейвола и становятся невидимы для пользователей. Этот метод гарантирует корректное отображение диалога поверх пейвола на всех платформах.


viewModelScope.launch {
    view.showDialog(
        title = "Close paywall?",
        content = "You will lose access to exclusive offers.",
        primaryActionTitle = "Stay",
        secondaryActionTitle = "Close"
    ).onSuccess { action ->
        if (action == AdaptyUIDialogActionType.SECONDARY) {
            // User confirmed - close the paywall
            view.dismiss()
        }
        // If primary - do nothing, user stays
    }.onError { error ->
        // handle the error
    }
}

Настройка стиля отображения на iOS

Настройте способ отображения пейвола на iOS, передав параметр iosPresentationStyle в метод present(). Параметр принимает значения AdaptyUIIOSPresentationStyle.FULLSCREEN (по умолчанию) или AdaptyUIIOSPresentationStyle.PAGESHEET.


viewModelScope.launch {
    val view = AdaptyUI.createPaywallView(paywall = paywall).getOrNull()
    view?.present(iosPresentationStyle = AdaptyUIIOSPresentationStyle.PAGESHEET)
}

Без Compose Multiplatform

createNativePaywallView входит в основной модуль io.adapty:adapty-kmp. Если ваш проект не использует Compose Multiplatform, зависимость io.adapty:adapty-kmp-ui не нужна.

Чтобы встроить пейвол без Compose Multiplatform, вызовите createNativePaywallView. Метод возвращает AdaptyNativePaywallView, который добавляется в ваш layout:


val nativeView = AdaptyUI.createNativePaywallView(
    context = context,
    viewModelStoreOwner = activity,
    paywall = paywall,
    observer = myPaywallObserver,
)

// Embed in your Compose layout:
AndroidView(
    factory = { nativeView.view },
    modifier = Modifier.fillMaxSize()
)

Поскольку методы по умолчанию KMP-интерфейсов становятся @required в Swift, вы не можете реализовать AdaptyUIPaywallsEventsObserver напрямую из Swift. Сначала объявите открытый базовый класс в iosMain:

open class BasePaywallObserver : AdaptyUIPaywallsEventsObserver

Затем создайте подкласс в Swift, переопределяя только нужное:

class MyPaywallObserver: BasePaywallObserver {
    override func paywallViewDidPerformAction(view: AdaptyUIPaywallView, action: any AdaptyUIAction) {
        if action is AdaptyUIActionCloseAction {
            // remove nativeView from your view hierarchy
        }
    }
}

let nativeView = AdaptyUI.shared.createNativePaywallView(
    paywall: paywall,
    observer: MyPaywallObserver()
)
// nativeView.viewController is a UIViewController.
// Add it to your SwiftUI view or UIKit hierarchy.

Освобождение ресурсов

Вызовите dispose() при удалении представления из макета. Это отменяет регистрацию слушателя событий и освобождает внутренние ресурсы.

nativeView.dispose()

Пользовательские теги

Пользовательские теги позволяют не создавать отдельные пейволы для разных сценариев. Представьте один пейвол, который динамически подстраивается под данные пользователя. Например, вместо безликого «Привет!» можно приветствовать пользователей лично: «Привет, Иван!» или «Привет, Анна!»

Вот несколько способов применения пользовательских тегов:

Отображать имя или email пользователя на пейволе.
Показывать текущий день недели для повышения продаж (например, «Хорошего четверга»).
Добавлять персонализированные сведения о продаваемых продуктах (например, название фитнес-программы или номер телефона в VoIP-приложении).

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

В некоторых случаях приложение может не знать, чем заменить пользовательский тег — особенно если пользователи работают со старой версией AdaptyUI SDK. Чтобы избежать этого, всегда добавляйте резервный текст, который будет заменять строки с неизвестными пользовательскими тегами. Без него пользователи могут увидеть теги в виде кода (<USERNAME/>).

Чтобы использовать пользовательские теги в пейволе, передайте их при создании представления пейвола:


viewModelScope.launch {
    val customTags = mapOf(
        "USERNAME" to "John",
        "DAY_OF_WEEK" to "Thursday"
    )

    AdaptyUI.createPaywallView(
        paywall = paywall,
        customTags = customTags
    ).onSuccess { view ->
        view.present()
    }.onError { error ->
        // handle the error
    }
}


val customTags = mapOf(
    "USERNAME" to "John",
    "DAY_OF_WEEK" to "Thursday"
)

val nativeView = AdaptyUI.createNativePaywallView(
    context = context,
    viewModelStoreOwner = activity,
    paywall = paywall,
    observer = myPaywallObserver,
    customTags = customTags,
)


val customTags = mapOf(
    "USERNAME" to "John",
    "DAY_OF_WEEK" to "Thursday"
)

val nativeView = AdaptyUI.createNativePaywallView(
    paywall = paywall,
    observer = myPaywallObserver,
    customTags = customTags,
)

Пользовательские таймеры

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

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


viewModelScope.launch {
    val customTimers = mapOf(
        "CUSTOM_TIMER_NY" to LocalDateTime(2025, 1, 1, 0, 0, 0),
        "CUSTOM_TIMER_SALE" to LocalDateTime(2024, 12, 31, 23, 59, 59)
    )

    AdaptyUI.createPaywallView(
        paywall = paywall,
        customTimers = customTimers
    ).onSuccess { view ->
        view.present()
    }.onError { error ->
        // handle the error
    }
}


val customTimers = mapOf(
    "CUSTOM_TIMER_NY" to LocalDateTime(2025, 1, 1, 0, 0, 0),
    "CUSTOM_TIMER_SALE" to LocalDateTime(2024, 12, 31, 23, 59, 59)
)

val nativeView = AdaptyUI.createNativePaywallView(
    context = context,
    viewModelStoreOwner = activity,
    paywall = paywall,
    observer = myPaywallObserver,
    customTimers = customTimers,
)


val customTimers = mapOf(
    "CUSTOM_TIMER_NY" to LocalDateTime(2025, 1, 1, 0, 0, 0),
    "CUSTOM_TIMER_SALE" to LocalDateTime(2024, 12, 31, 23, 59, 59)
)

val nativeView = AdaptyUI.createNativePaywallView(
    paywall = paywall,
    observer = myPaywallObserver,
    customTimers = customTimers,
)