展示流程与付费墙 - Kotlin Multiplatform

如果你已创建了流程或付费墙，无需在移动应用代码中手动处理其渲染逻辑来向用户展示。流程或付费墙本身已包含展示内容和展示方式的完整定义。

本指南适用于由 Adapty 渲染的流程和新付费墙编辑工具付费墙。远程配置付费墙和 Observer 模式的处理方式有所不同。

有关呈现远程配置付费墙，请参阅呈现远程配置设计的付费墙。
有关在Observer 模式下呈现流程，请参阅在 Observer 模式下呈现流程。

要获取下面使用的 flow 对象，请参阅获取流程与付费墙。

Adapty Kotlin Multiplatform SDK 提供两种呈现流程和付费墙的方式：

使用 Compose Multiplatform
不使用 Compose Multiplatform

使用 Compose Multiplatform

要展示流程或付费墙，请在通过 createFlowView 方法创建的 view 上调用 view.present() 方法。每个 view 只能使用一次。如果需要再次展示流程，请重新调用 createFlowView 创建一个新的 view 实例。

重复使用同一个 view 而不重新创建，可能会导致报错。


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

显示对话框

在 Android 上展示流程或付费墙时，请使用此方法替代原生 alert 对话框。在 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 展示样式

通过向 present() 方法传入 iosPresentationStyle 参数，可以配置流程或付费墙在 iOS 上的展示方式。该参数接受 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()
)

默认情况下，嵌入式视图不会应用安全区域内边距——您的布局需要自行处理插边。如果希望视图自行应用安全区域内边距，请在 createNativeFlowView 中传入 androidEnableSafeArea = true。该参数仅适用于 Android。

由于 KMP 接口的默认方法在 Swift 中会变为 @required，您无法直接在 Swift 中实现 AdaptyUIFlowsEventsObserver。请先在 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()

自定义标签

自定义标签让你无需为不同场景创建单独的流程或付费墙。想象一个可以根据用户数据动态调整的流程：不再是千篇一律的”你好！“，而是亲切地问候”你好，John！“或”你好，Ann！”

以下是自定义标签的一些使用场景：

在流程或付费墙上显示用户的姓名或邮箱。
展示当天是星期几以促进销售（例如”周四快乐”）。
为销售的产品添加个性化信息（如健身计划名称，或 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,
)

如果您已使用付费墙编辑工具自定义了付费墙，则无需在移动应用代码中额外处理渲染逻辑即可将其展示给用户。此类付费墙已包含展示内容及展示方式的完整配置。

本指南仅适用于新版付费墙编辑工具构建的付费墙。使用远程配置付费墙和 Observer 模式设计的付费墙，其展示流程有所不同。

如需展示远程配置付费墙，请参阅渲染远程配置设计的付费墙。

Adapty Kotlin Multiplatform SDK 提供了两种展示付费墙的方式：

使用 Compose Multiplatform
不使用 Compose Multiplatform

使用 Compose Multiplatform

要显示付费墙，请在由 createPaywallView 方法创建的 view 上调用 view.present() 方法。每个 view 只能使用一次。如果需要再次显示付费墙，请重新调用 createPaywallView 创建一个新的 view 实例。

重复使用同一个 view 而不重新创建，可能会导致错误。


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

显示对话框

在 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 呈现样式

通过向 present() 方法传递 iosPresentationStyle 参数，可以配置付费墙在 iOS 上的呈现方式。该参数接受 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，你可以将其添加到布局中：


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 接口的默认方法在 Swift 中会变为 @required，因此无法直接从 Swift 实现 AdaptyUIPaywallsEventsObserver。请先在 iosMain 中声明一个 open 基类：

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()

自定义标签

自定义标签让你无需为不同场景创建多个付费墙，只需一个付费墙即可根据用户数据动态调整内容。例如，与其显示通用的”你好！“，不如用”你好，John！“或”你好，Ann！“来个性化问候用户。

以下是自定义标签的一些使用场景：

在付费墙上展示用户的姓名或邮箱。
显示当前是星期几以促进销售（例如，“愉快的星期四”）。
为你销售的产品添加个性化详情（如健身计划的名称，或 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,
)

自定义计时器

付费墙计时器是推广限时特惠和季节性活动的利器。但需要注意的是，这个计时器与优惠的有效期或活动的持续时间无关。它只是一个独立的倒计时，从你设定的值开始递减至零。计时器归零后不会触发任何操作——它只会停在零。

你可以自定义计时器前后的文字，以呈现所需的提示信息，例如：“优惠剩余时间：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.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,
)