在 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	✅ 简单	您在无代码编辑工具中创建完整的、可立即购买的流程。Adapty 自动渲染并在后台处理所有复杂的购买流程、收据验证和订阅管理。
手动创建付费墙	🟡 中等	您在应用代码中实现付费墙 UI，但仍通过 Adapty 获取流程对象，以保持产品供应的灵活性。请参阅指南。
观察者模式	🔴 复杂	您已有自己的购买处理基础设施并希望继续使用。请注意，观察者模式在 Adapty 中存在一定限制。请参阅文章。

以下步骤介绍如何实现在 Adapty Flow Builder 中创建的流程。

如果您希望自行构建付费墙 UI，请参阅手动实现付费墙。

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

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

开始之前

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

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

完成这些步骤的最快方式是参照快速入门指南，或使用 Developer CLI 创建流程和版位。

1. 获取流程

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

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

使用 getFlow 方法，通过版位 ID 获取 flow 对象。
使用 createFlowView 方法创建流程视图。该视图包含显示流程所需的 UI 元素和样式。如果流程没有配置视图，createFlowView 将返回错误——请在 onError 中处理该错误。

要获取视图，必须在 Flow Builder 中开启 Show on device 开关。否则，createFlowView 将返回错误，流程也不会显示。

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
    }