在 Kotlin Multiplatform SDK 中使用 Flow Builder 启用购买

本指南使用 Adapty Kotlin Multiplatform SDK v4 (beta) API。如果你使用的是 v3，请参阅迁移指南了解对应的方法名称。

要启用应用内购买，你需要了解以下三个核心概念：

• 产品 – 用户可以购买的内容（订阅、消耗型商品、永久授权）
• 流程 – 向用户展示产品的页面序列，通过无代码的 Flow Builder 构建。SDK 通过 getFlow 获取流程。如果你更倾向于用自己的代码构建 UI，请使用付费墙代替——参见手动实现付费墙。
• 版位 – 流程在应用中展示的位置和时机（如 main、onboarding、settings）。你在看板中将流程绑定到版位，然后在代码中通过版位 ID 请求。这样可以轻松进行 A/B 测试，向不同用户展示不同的流程。

Adapty 为您提供三种在应用中开启购买功能的方式。请根据您的应用需求选择其中一种：

要在应用代码中展示 Adapty Flow Builder 创建的流程，您只需：

1. 获取流程：从 Adapty 获取流程。
2. 展示流程，Adapty 将自动处理购买：在应用中显示视图。
3. 处理按钮操作：将用户交互与应用的响应关联起来。例如，在用户点击按钮时打开链接或关闭流程。

开始之前

开始之前，请完成以下步骤：

1. 在 Adapty 看板中将你的应用连接至 App Store 和/或 Google Play。
2. 在 Adapty 中创建产品。
3. 创建流程并向其中添加产品。
4. 创建版位并将流程添加到其中。
5. 在你的应用代码中安装并激活 Adapty SDK。

1. 获取流程

你的流程与在看板中配置的版位相关联。版位允许你为不同的目标受众运行不同的流程，或运行 A/B 测试。

要获取在 Adapty 付费墙编辑工具中创建的流程，你需要：

1. 使用 getFlow 方法，通过版位 ID 获取 flow 对象。

2. 使用 createFlowView 方法创建流程视图。该视图包含显示流程所需的 UI 元素和样式。如果流程没有配置视图，createFlowView 将返回错误——请在 onError 中处理该错误。

Adapty.getFlow("YOUR_PLACEMENT_ID")
    .onSuccess { flow ->
        AdaptyUI.createFlowView(flow)
            .onSuccess { view ->
                view.present()
            }
            .onError { error ->
                // the flow has no view configured, or view creation failed
            }
    }
    .onError { error ->
        // handle the error
    }

2. 展示流程

现在，当你已获取到流程后，只需添加几行代码即可展示它。

要在设备屏幕上展示可视化流程，必须先创建视图。为此，请调用 AdaptyUI.createFlowView() 方法：

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

成功创建视图后，你可以将其呈现在设备屏幕上。每个视图只能使用一次：调用 dismiss() 后，需再次调用 createFlowView 才能重新显示流程。

3. 处理按钮操作

当用户点击流程中的按钮时，Kotlin Multiplatform SDK 会自动处理购买、恢复、关闭流程以及打开链接等操作。

但是，其他按钮具有自定义或预定义的 ID，需要在代码中处理相应操作。或者，你可能希望覆盖它们的默认行为。

例如，以下是关闭按钮的默认行为。你无需在代码中添加此内容，但在这里你可以看到如果需要时应如何实现。

请注意，默认情况下，流程在购买成功后仍保持打开状态。如果您希望在购买完成后关闭它，请在 flowViewDidFinishPurchase 回调中关闭该视图。

AdaptyUI.setFlowsEventsObserver(object : AdaptyUIFlowsEventsObserver {
    override fun flowViewDidPerformAction(view: AdaptyUIFlowView, action: AdaptyUIAction) {
        when (action) {
            is AdaptyUIAction.CloseAction -> mainUiScope.launch { view.dismiss() }
            else -> Unit
        }
    }

    override fun flowViewDidFinishPurchase(
        view: AdaptyUIFlowView,
        product: AdaptyPaywallProduct,
        purchaseResult: AdaptyPurchaseResult
    ) {
        if (purchaseResult !is AdaptyPurchaseResult.UserCanceled) {
            mainUiScope.launch { view.dismiss() }
        }
    }
})

后续步骤

您的流程已准备好在应用中展示。在 App Store 沙盒或 Google Play Store 中测试购买，确保您可以从流程中完成测试购买。

接下来，您需要检查用户的访问等级，以确保向正确的用户展示流程或开放付费功能。

完整示例

以下是如何将所有这些步骤整合到您的应用中的完整示例。

// Set up the observer for handling flow events
AdaptyUI.setFlowsEventsObserver(object : AdaptyUIFlowsEventsObserver {
    override fun flowViewDidPerformAction(view: AdaptyUIFlowView, action: AdaptyUIAction) {
        when (action) {
            is AdaptyUIAction.CloseAction -> mainUiScope.launch { view.dismiss() }
            else -> Unit
        }
    }

    override fun flowViewDidFinishPurchase(
        view: AdaptyUIFlowView,
        product: AdaptyPaywallProduct,
        purchaseResult: AdaptyPurchaseResult
    ) {
        if (purchaseResult !is AdaptyPurchaseResult.UserCanceled) {
            mainUiScope.launch { view.dismiss() }
        }
    }
})

// Get and display the flow
Adapty.getFlow("YOUR_PLACEMENT_ID")
    .onSuccess { flow ->
        AdaptyUI.createFlowView(flow)
            .onSuccess { view ->
                view.present()
            }
            .onError { error ->
                // the flow has no view configured — use custom logic
            }
    }
    .onError { error ->
        // handle the error
    }