在 Kotlin Multiplatform SDK 中获取远程配置付费墙的付费墙和产品

在展示远程配置和自定义付费墙之前，您需要先获取相关信息。请注意，本主题涉及远程配置和自定义付费墙。如需了解如何获取付费墙编辑工具自定义付费墙的相关指导，请参阅获取付费墙编辑工具付费墙及其配置。

想了解 Adapty SDK 如何集成到移动应用中的真实示例？请查看我们的示例应用，其中展示了完整的配置过程，包括显示付费墙、完成购买以及其他基本功能。

在您开始在移动应用中获取付费墙和产品之前（点击展开）

在 Adapty 看板中创建您的产品。
在 Adapty 看板中创建付费墙并将产品整合到付费墙中。
在 Adapty 看板中创建版位并将付费墙整合到版位中。
在您的移动应用中安装 Adapty SDK。

获取付费墙信息

在 Adapty 中，产品是 App Store 和 Google Play 产品的组合体。这些跨平台产品被整合到付费墙中，使您能够在特定的移动应用版位中展示它们。

要展示产品，您需要使用 getPaywall 方法从某个版位获取付费墙。

不要硬编码产品 ID。 您唯一需要硬编码的 ID 是版位 ID。付费墙是远程配置的，因此产品数量和可用优惠随时可能变化。您的应用必须动态处理这些变化——如果今天付费墙返回两个产品，明天返回三个，则无需修改代码即可全部展示。

import com.adapty.kmp.Adapty
import com.adapty.kmp.models.AdaptyPaywallFetchPolicy

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`	默认情况下，SDK 将尝试从服务器加载数据，若加载失败则返回缓存数据。我们推荐此方式，因为它可确保用户始终获得最新数据。但是，如果您认为用户的网络连接不稳定，可以考虑使用 `AdaptyPaywallFetchPolicy.ReturnCacheDataElseLoad`，在缓存存在时返回缓存数据。在这种情况下，用户可能无法获得最新数据，但无论网络状况如何，加载速度都会更快。缓存会定期更新，因此在会话期间使用缓存以避免网络请求是安全的。请注意，缓存在重启应用后仍会保留，只有在重新安装应用或手动清理时才会被清除。 Adapty SDK 将付费墙存储在两个层级：上述定期更新的缓存和备用付费墙。我们还使用 CDN 来加快付费墙获取速度，并在 CDN 不可访问时使用独立的备用服务器。此系统旨在确保您始终获得最新版本的付费墙，同时即使在网络连接不稳定的情况下也能保证可靠性。
loadTimeout	默认值：5 秒	此值限制该方法的超时时间。如果超时，将返回缓存数据或本地备用数据。请注意，在极少数情况下，此方法的超时时间可能略晚于 `loadTimeout` 中指定的时间，因为该操作可能在底层包含不同的请求。

不要硬编码产品 ID！由于付费墙是远程配置的，可用产品、产品数量和特殊优惠（例如免费试用）可能随时变化。请确保您的代码能够处理这些场景。
例如，如果您最初获取到 2 个产品，您的应用应显示这 2 个产品。但如果您后来获取到 3 个产品，您的应用应显示全部 3 个产品，而无需修改任何代码。您唯一需要硬编码的是版位 ID。

响应参数：

参数	描述
Paywall	一个 `AdaptyPaywall` 对象，包含：产品 ID 列表、付费墙标识符、远程配置以及其他几个属性。

获取产品

获取付费墙后，您可以查询与其对应的产品数组：

Adapty.getPaywallProducts(paywall).onSuccess { products ->
    // the requested products
}.onError { error ->
    // handle the error
}

响应参数：

参数	描述
Products	`AdaptyPaywallProduct` 对象列表，包含：产品标识符、产品名称、价格、货币、订阅时长以及其他几个属性。

在实现您自己的付费墙设计时，您可能需要访问 AdaptyPaywallProduct 对象中的这些属性。以下是最常用的属性，但请参阅链接文档以获取所有可用属性的完整详情。

属性	描述
Title	要显示产品标题，请使用 `product.localizedTitle`。请注意，本地化基于用户选择的商店国家/地区，而非设备本身的语言环境。
Price	要显示本地化版本的价格，请使用 `product.price.localizedString`。此本地化基于设备的语言环境信息。您也可以使用 `product.price.amount` 以数字形式访问价格。该值将以本地货币提供。要获取相关货币符号，请使用 `product.price.currencySymbol`。
Subscription Period	要显示订阅周期（例如周、月、年等），请使用 `product.subscriptionDetails?.localizedSubscriptionPeriod`。此本地化基于设备的语言环境。要以编程方式获取订阅周期，请使用 `product.subscriptionDetails?.subscriptionPeriod`。从中您可以访问 `unit` 枚举以获取时长（即 DAY、WEEK、MONTH、YEAR 或 UNKNOWN）。`numberOfUnits` 值将获取周期单位的数量。例如，对于季度订阅，您会在 unit 属性中看到 `MONTH`，在 numberOfUnits 属性中看到 `3`。
Introductory Offer	要显示徽章或其他指示器以表明订阅包含新用户优惠，请查看 `product.subscriptionDetails?.introductoryOfferPhases` 属性。这是一个最多可包含两个折扣阶段的列表：免费试用阶段和优惠价格阶段。每个阶段对象中包含以下有用属性： • `paymentMode`：枚举，值为 `FREE_TRIAL`、`PAY_AS_YOU_GO`、`PAY_UPFRONT` 和 `UNKNOWN`。免费试用属于 `FREE_TRIAL` 类型。 • `price`：折扣价格（数字形式）。免费试用时此处为 `0`。 • `localizedNumberOfPeriods`：使用设备语言环境本地化的字符串，描述优惠时长。例如，三天试用优惠在此字段中显示为 `3 days`。 • `subscriptionPeriod`：您也可以通过此属性获取优惠周期的各个详情。其对优惠的使用方式与上一节所述相同。 • `localizedSubscriptionPeriod`：以用户语言环境格式化的折扣订阅周期。

使用默认目标受众付费墙加快付费墙获取速度

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

为解决此问题，您可以使用 getPaywallForDefaultAudience 方法，该方法获取指定版位针对 All Users 目标受众的付费墙。但是，至关重要的是要理解，推荐的方法是通过 getPaywall 方法获取付费墙，如上文获取付费墙信息部分所述。

为什么我们推荐使用 getPaywall

getPaywallForDefaultAudience 方法存在一些显著缺点：

潜在的向后兼容性问题：如果您需要为不同的应用版本（当前版本和未来版本）显示不同的付费墙，您可能会面临挑战。您要么必须设计支持当前（旧版）版本的付费墙，要么接受使用当前（旧版）版本的用户可能遇到付费墙无法渲染的问题。
失去精准定向：所有用户都将看到为 All Users 目标受众设计的相同付费墙，这意味着您将失去个性化定向功能（包括基于国家/地区、营销归因或您自己的自定义属性）。

如果您愿意接受这些缺点以从更快的付费墙获取中受益，请按如下方式使用 getPaywallForDefaultAudience 方法。否则，请坚持使用上文所述的 getPaywall。

import com.adapty.kmp.Adapty
import com.adapty.kmp.models.AdaptyPaywall
import com.adapty.kmp.models.AdaptyPaywallFetchPolicy
import com.adapty.kmp.models.onError
import com.adapty.kmp.models.onSuccess

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

默认情况下，SDK 将尝试从服务器加载数据，若加载失败则返回缓存数据。我们推荐此方式，因为它可确保用户始终获得最新数据。

但是，如果您认为用户的网络连接不稳定，可以考虑使用 AdaptyPaywallFetchPolicy.ReturnCacheDataElseLoad，在缓存存在时返回缓存数据。在这种情况下，用户可能无法获得最新数据，但无论网络状况如何，加载速度都会更快。缓存会定期更新，因此在会话期间使用缓存以避免网络请求是安全的。

请注意，缓存在重启应用后仍会保留，只有在重新安装应用或手动清理时才会被清除。