获取流程与付费墙 - Kotlin Multiplatform

在设计好流程之后，你可以在移动应用中展示它。第一步是获取与版位关联的流程或付费墙及其视图配置，具体步骤如下所示。

开始之前

您需要：

• Adapty 看板中的产品：创建您的产品。
• 包含产品的流程：在流程与付费墙编辑工具中构建，并为其分配产品。
• 版位：创建版位并将您的流程分配给它。
• 已安装 Adapty SDK：请参阅 Kotlin Multiplatform SDK 安装指南。

获取流程/付费墙

如果你已经在编辑工具中设计好了流程或付费墙，无需在移动端代码中额外编写渲染逻辑来向用户展示它。这类流程或付费墙本身已包含展示内容和展示方式的完整定义。不过，你仍需通过版位获取其 ID 和视图配置，然后再在移动端进行呈现。

为确保最佳性能，请尽早获取流程或付费墙及其视图配置，以便在向用户展示之前有足够的时间下载图片。

使用 getFlow 方法获取流程或付费墙：

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

参数：

参数	是否必填	描述
placementId	必填	目标版位的标识符。即你在 Adapty 看板创建版位时指定的值。
fetchPolicy	默认值：AdaptyPaywallFetchPolicy.Default	fetchPolicy 决定 SDK 优先从哪一层读取数据，而非是否允许使用缓存。默认情况下，SDK 会先请求服务器，若请求失败则返回缓存数据。推荐使用此方式，因为它能确保用户始终获取最新数据。 但如果你认为用户的网络环境不稳定，可以考虑使用 AdaptyPaywallFetchPolicy.ReturnCacheDataElseLoad，该策略与默认顺序相反——优先读取缓存，只有在没有缓存时才请求服务器。用户获取的数据可能不是最新的，但无论网络状况多差，加载速度都会更快。缓存会定期更新，因此在会话期间使用缓存以减少网络请求是安全的。 第三种策略 AdaptyPaywallFetchPolicy.ReturnCacheDataIfNotExpiredElseLoad(maxAgeMillis) 介于两者之间：当缓存数据的时效在 maxAgeMillis 以内时优先读取缓存，超过该时效后才请求服务器。 请注意，重启应用不会清除缓存，只有在重新安装应用或手动清理时才会被清除。 Adapty SDK 将流程和付费墙存储在两个层级：上述定期更新的缓存层，以及备用付费墙。我们还使用 CDN 加快获取速度，并在 CDN 不可达时提供独立的备用服务器。该机制旨在确保你始终获取最新版本，同时在网络条件较差的情况下也能保证可靠性。
loadTimeout	默认值：5 秒	该值限制本方法的超时时间。如果超时，将返回缓存数据或本地备用数据。 请注意，在极少数情况下，该方法的实际超时时间可能略晚于 loadTimeout 中设定的值，因为底层操作可能包含多个请求。 对于 Kotlin Multiplatform：你可以使用扩展函数创建 Duration，例如 5.seconds，其中 .seconds 来自 kotlin.time.Duration.Companion.seconds。

响应参数：

参数	描述
Flow	一个 AdaptyFlow 对象，包含版位、标识符（instanceIdentity、variationId）、名称、付费墙变体（paywalls——AdaptyFlowPaywall 列表）以及远程配置（remoteConfigs——每个语言区域对应一条记录）。如需预加载产品、自定义 UI 或以编程方式检查，请调用 getPaywallProducts(flow)。

获取视图配置

获取流程或付费墙后，使用 createFlowView 方法一步完成视图配置的加载并创建视图。无需单独检查标志：若版位是在 Flow & Paywall Builder（流程）或旧版付费墙编辑工具（付费墙）中设计的，createFlowView 会返回可直接展示的视图。若版位是没有编辑工具界面的自定义付费墙，createFlowView 将返回 AdaptyResult.Error —— 按远程配置付费墙处理。

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	必填	通过 Adapty.getFlow 获取的 AdaptyFlow 对象。
locale	可选	用于渲染视图的流程本地化标识符，例如 en 或 pt-br。若省略，视图将以 en 渲染；若流程没有 en 版本，则使用流程的默认本地化。详见本地化与语言代码。
customLayoutId	可选 默认值：null SDK 4.1+	在 Flow Builder 中定义的布局自定义 ID。传入此值可渲染指定布局，而非 SDK 根据设备类型和屏幕尺寸自动选择的布局。若没有与该 ID 匹配的布局，流程将在无视图配置的情况下加载。
loadTimeout	可选	该值限制此方法的超时时间。若达到超时时间，将返回缓存数据或本地备用数据。请注意，在极少数情况下，此方法的实际超时时间可能略晚于 loadTimeout 中指定的时间，因为该操作底层可能由多个请求组成。可使用 kotlin.time.Duration.Companion 中的扩展函数，例如 5.seconds。
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	fetchPolicy 决定 SDK 优先从哪一层读取数据，而不是是否可以使用缓存。默认情况下，SDK 会优先请求服务器，如果请求失败则返回缓存数据。我们推荐这种方式，因为它能确保用户始终获取最新数据。 但如果您认为用户的网络状况不稳定，可以考虑使用 AdaptyPaywallFetchPolicy.ReturnCacheDataElseLoad，该策略的读取顺序相反——优先读取缓存，仅在没有缓存时才请求服务器。用户获取的数据可能不是最新的，但无论网络状况多差，加载速度都会更快。缓存会定期更新，因此在会话期间使用缓存以减少网络请求是安全的。 第三种策略 AdaptyPaywallFetchPolicy.ReturnCacheDataIfNotExpiredElseLoad(maxAgeMillis) 介于两者之间：当缓存时间未超过 maxAgeMillis 时优先读取缓存，超过后再请求服务器。 请注意，缓存在应用重启后仍会保留，只有在重新安装应用或手动清除时才会被清空。

自定义资源

要自定义流程或付费墙中的图片和视频，请实现自定义资源。

主图和视频有预定义的 ID：hero_image 和 hero_video。在自定义资源包中，你通过这些 ID 来定位相应元素并自定义其行为。

对于其他图片和视频，你需要在 Adapty 看板中设置自定义 ID。

例如，你可以：

• 向部分用户显示不同的图片或视频。
• 在远程主图加载时，先显示本地预览图。
• 在播放视频前，先显示预览图。

以下是如何通过 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"
        )
    )

    // 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
    }
}

在 使用 Adapty 看板中的旧版付费墙编辑工具完成付费墙视觉设计 后，您可以在移动应用中展示它。第一步是获取与版位关联的付费墙及其视图配置，详见下文。

请注意，本主题适用于使用付费墙编辑工具自定义的付费墙。如果您是手动实现付费墙，请参阅在移动应用中获取远程配置付费墙的付费墙与产品主题。

在移动应用中展示付费墙之前（点击展开）

1. 在 Adapty 看板中创建产品。
2. 在 Adapty 看板中创建付费墙并将产品添加到其中。
3. 在 Adapty 看板中创建版位并将付费墙添加到其中。
4. 在移动应用中安装 Adapty SDK。

获取使用付费墙编辑工具设计的付费墙

如果您已使用付费墙编辑工具设计了付费墙，则无需在移动应用代码中处理其渲染逻辑即可向用户展示。此类付费墙同时包含展示内容和展示方式。但您仍需通过版位获取其 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	fetchPolicy 用于设置 SDK 优先从哪一层读取数据，而非决定是否可以使用缓存。默认情况下，SDK 会优先请求服务器，若请求失败则返回缓存数据。我们推荐使用此方案，因为它能确保用户始终获取到最新数据。 但如果您认为用户的网络环境不稳定，可以考虑使用 AdaptyPaywallFetchPolicy.ReturnCacheDataElseLoad，该策略与默认策略顺序相反——优先读取缓存，仅在缓存为空时才请求服务器。用户获取到的数据可能不是最新的，但无论网络状况如何，加载速度都会更快。缓存会定期更新，因此在同一会话中使用缓存来避免重复网络请求是安全的。 第三种策略 AdaptyPaywallFetchPolicy.ReturnCacheDataIfNotExpiredElseLoad(maxAgeMillis) 介于两者之间：当缓存数据的存续时间短于 maxAgeMillis 时优先读取缓存，超过该时间后则请求服务器。 请注意，重启应用不会清除缓存，只有在重新安装应用或手动清理时才会清空缓存。 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 对象，包含产品 ID 列表、付费墙标识符、远程配置及其他若干属性。

获取使用付费墙编辑工具设计的付费墙的视图配置

获取付费墙后，检查其是否包含 ViewConfiguration，这表示该付费墙是使用付费墙编辑工具创建的。这将指导您如何展示该付费墙。如果存在 ViewConfiguration，则将其视为付费墙编辑工具付费墙；否则，将其作为远程配置付费墙处理。

使用 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
}

参数	是否必填	描述
paywall	必填	用于获取目标付费墙控制器的 AdaptyPaywall 对象。
loadTimeout	可选	此值限制该方法的超时时间。如果达到超时，将返回缓存数据或本地备用数据。请注意，在极少数情况下，此方法的超时时间可能略晚于 loadTimeout 中指定的时间，因为该操作在底层可能由多个不同请求组成。您可以使用 kotlin.time.Duration.Companion 中的扩展函数，如 5.seconds。
preloadProducts	可选	设置为 true 以预加载产品从而提升性能。启用后，产品将提前加载，减少展示付费墙所需的时间。
productPurchaseParams	可选	从 AdaptyProductIdentifier 到 AdaptyPurchaseParameters 的映射。使用此参数为付费墙中的各个产品配置特定的购买参数，例如个性化优惠或订阅更新参数。

加载完成后，展示付费墙。

为默认目标受众获取付费墙以加快获取速度

通常情况下，付费墙的获取几乎是即时完成的，您无需担心加速此过程。但是，如果您拥有大量目标受众和付费墙，且用户的网络连接较弱，付费墙的获取时间可能比预期更长。在这种情况下，您可能希望展示默认付费墙以确保流畅的用户体验，而不是完全不展示付费墙。

为解决这一问题，您可以使用 getPaywallForDefaultAudience 方法，该方法为所有用户目标受众获取指定版位的付费墙。但请务必了解，推荐的方式是使用 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	fetchPolicy 设置 SDK 优先读取哪一层数据，而非是否可以使用缓存。默认情况下，SDK 会先请求服务器，若请求失败则返回缓存数据。我们推荐使用这种方式，因为它能确保用户始终获取最新数据。 但如果您认为用户的网络环境不稳定，可以考虑使用 AdaptyPaywallFetchPolicy.ReturnCacheDataElseLoad，该策略与默认策略顺序相反——优先读取缓存，仅在没有缓存时才请求服务器。用户可能无法获取最新数据，但无论网络状况如何，加载速度都会更快。缓存会定期更新，因此在会话期间使用缓存以避免网络请求是安全的。 第三种策略 AdaptyPaywallFetchPolicy.ReturnCacheDataIfNotExpiredElseLoad(maxAgeMillis) 介于两者之间：当缓存数据的存在时间短于 maxAgeMillis 时优先读取缓存，超过该时间后才请求服务器。 请注意，缓存在应用重启后仍会保留，只有在重新安装应用或手动清理时才会被清除。

自定义素材

要自定义付费墙中的图片和视频，请实现自定义素材。

主图和视频具有预定义的 ID：hero_image 和 hero_video。在自定义素材包中，您通过这些 ID 定位相应元素并自定义其行为。

对于其他图片和视频，您需要在 Adapty 看板中设置自定义 ID。

例如，您可以：

• 向部分用户展示不同的图片或视频。
• 在远程主图加载时展示本地预览图。
• 在播放视频前展示预览图。

以下是通过映射提供自定义素材的示例：

// 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
    }
}