---
title: "在 Android SDK 中获取付费墙编辑工具付费墙及其配置"
description: "了解如何在 Adapty 中为您的 Android 应用检索付费墙编辑工具付费墙，以更好地控制订阅。"
---
在 Adapty 看板中[使用新版付费墙编辑工具设计完付费墙的视觉部分](adapty-paywall-builder)后，您可以在移动应用中展示它。此过程的第一步是获取与版位关联的付费墙及其视图配置，如下所述。
:::warning
新版付费墙编辑工具需要 Android SDK 3.0 或更高版本。如需在 Adapty SDK v2 中展示使用旧版付费墙编辑工具设计的付费墙，请参阅[展示使用旧版付费墙编辑工具设计的付费墙](android-present-paywalls-legacy)。
:::
请注意，本主题涉及通过付费墙编辑工具自定义的付费墙。如果您是手动实现付费墙，请参阅[在移动应用中为远程配置付费墙获取付费墙和产品](fetch-paywalls-and-products-android)主题。
:::tip
想了解 Adapty SDK 如何集成到移动应用中的真实示例？请查看我们的[示例应用](sample-apps)，其中展示了完整的配置过程，包括显示付费墙、完成购买以及其他基本功能。
:::
在移动应用中开始展示付费墙之前（点击展开）
1. 在 Adapty 看板中[创建您的产品](create-product)。
2. 在 Adapty 看板中[创建付费墙并将产品加入其中](create-paywall)。
3. 在 Adapty 看板中[创建版位并将付费墙加入其中](create-placement)。
4. 在移动应用中安装 [Adapty SDK](sdk-installation-android)。
## 获取使用付费墙编辑工具设计的付费墙 \{#fetch-paywall-designed-with-paywall-builder\}
如果您[使用付费墙编辑工具设计了付费墙](adapty-paywall-builder)，则无需在移动应用代码中手动渲染它来向用户展示。此类付费墙同时包含展示内容和展示方式。尽管如此，您仍需要通过版位获取其 ID、视图配置，然后在移动应用中进行展示。
为确保最佳性能，务必尽早获取付费墙及其[视图配置](android-get-pb-paywalls#fetch-the-view-configuration-of-paywall-designed-using-paywall-builder)，以便在向用户展示之前有足够的时间下载图片。
使用 `getPaywall` 方法获取付费墙：
```kotlin showLineNumbers
...
Adapty.getPaywall("YOUR_PLACEMENT_ID", locale = "en", loadTimeout = 10.seconds) { result ->
when (result) {
is AdaptyResult.Success -> {
val paywall = result.value
// the requested paywall
}
is AdaptyResult.Error -> {
val error = result.error
// handle the error
}
}
}
```
```java showLineNumbers
...
Adapty.getPaywall("YOUR_PLACEMENT_ID", "en", TimeInterval.seconds(10), result -> {
if (result instanceof AdaptyResult.Success) {
AdaptyPaywall paywall = ((AdaptyResult.Success) result).getValue();
// the requested paywall
} else if (result instanceof AdaptyResult.Error) {
AdaptyError error = ((AdaptyResult.Error) result).getError();
// handle the error
}
});
```
参数：
| 参数 | 是否必填 | 描述 |
|---------|--------|-----------|
| **placementId** | 必填 | 所需[版位](placements)的标识符。这是您在 Adapty 看板中创建版位时指定的值。 |
| **locale** | 可选
默认值：`en`
| [付费墙本地化](add-paywall-locale-in-adapty-paywall-builder)的标识符。该参数应为由一个或两个子标签组成的语言代码，子标签之间用减号（**-**）分隔。第一个子标签表示语言，第二个表示地区。
示例：`en` 表示英语，`pt-br` 表示巴西葡萄牙语。
有关语言代码及推荐使用方式的更多信息，请参阅[本地化与语言代码](localizations-and-locale-codes)。
|
| **fetchPolicy** | 默认值：`.reloadRevalidatingCacheData` | 默认情况下，SDK 将尝试从服务器加载数据，如果失败则返回缓存数据。我们推荐此选项，因为它可确保用户始终获取最新数据。
但是，如果您认为用户的网络连接不稳定，可以考虑使用 `.returnCacheDataElseLoad`，在缓存数据存在时返回缓存数据。在这种情况下，用户获取的数据可能不是最新的，但无论网络连接质量如何，都能获得更快的加载速度。缓存会定期更新，因此在会话期间使用缓存以避免网络请求是安全的。
请注意，缓存在应用重启后仍然保留，只有在重新安装应用或手动清理时才会清除。
Adapty SDK 在两层本地存储中保存付费墙：上述定期更新的缓存和[备用付费墙](fallback-paywalls)。我们还使用 CDN 加快付费墙的获取速度，并在 CDN 不可用时使用独立的备用服务器。该系统旨在确保您始终获取最新版本的付费墙，同时在网络连接不稳定时仍能保证可靠性。
|
| **loadTimeout** | 默认值：5 秒 | 此值限制该方法的超时时间。如果达到超时，将返回缓存数据或本地备用数据。
请注意，在极少数情况下，此方法的超时时间可能比 `loadTimeout` 中指定的时间稍长，因为该操作可能包含多个底层请求。
对于 Android：您可以使用扩展函数创建 `TimeInterval`（例如 `5.seconds`，其中 `.seconds` 来自 `import com.adapty.utils.seconds`），或使用 `TimeInterval.seconds(5)`。若不设置限制，请使用 `TimeInterval.INFINITE`。
|
响应参数：
| 参数 | 描述 |
| :-------- |:----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Paywall | 一个 [`AdaptyPaywall`](https://android.adapty.io/adapty/com.adapty.models/-adapty-paywall/) 对象，包含产品 ID 列表、付费墙标识符、远程配置及其他多个属性。 |
## 获取使用付费墙编辑工具设计的付费墙的视图配置 \{#fetch-the-view-configuration-of-paywall-designed-using-paywall-builder\}
:::important
请确保在付费墙编辑工具中启用了 **Show on device** 开关。如果未开启此选项，将无法获取视图配置。
:::
获取付费墙后，检查其是否包含 `ViewConfiguration`，这表明该付费墙是使用付费墙编辑工具创建的。这将指导您如何展示付费墙。如果存在 `ViewConfiguration`，则将其视为付费墙编辑工具付费墙；否则，[将其作为远程配置付费墙处理](present-remote-config-paywalls)。
使用 `getViewConfiguration` 方法加载视图配置。
```kotlin showLineNumbers
if (!paywall.hasViewConfiguration) {
// use your custom logic
return
}
AdaptyUI.getViewConfiguration(paywall, loadTimeout = 10.seconds) { result ->
when(result) {
is AdaptyResult.Success -> {
val viewConfiguration = result.value
// use loaded configuration
}
is AdaptyResult.Error -> {
val error = result.error
// handle the error
}
}
}
```
| 参数 | 是否必填 | 描述 |
| :-------------- | :------------- | :----------------------------------------------------------- |
| **paywall** | 必填 | 一个 `AdaptyPaywall` 对象，用于获取所需付费墙的控制器。 |
| **loadTimeout** | 默认值：5 秒 | 此值限制该方法的超时时间。如果达到超时，将返回缓存数据或本地备用数据。请注意，在极少数情况下，此方法的超时时间可能比 `loadTimeout` 中指定的时间稍长，因为该操作可能包含多个底层请求。 |
使用 `getViewConfiguration` 方法加载视图配置。
```java showLineNumbers
if (!paywall.hasViewConfiguration()) {
// use your custom logic
return;
}
AdaptyUI.getViewConfiguration(paywall, TimeInterval.seconds(10), result -> {
if (result instanceof AdaptyResult.Success) {
AdaptyUI.LocalizedViewConfiguration viewConfiguration =
((AdaptyResult.Success) result).getValue();
// use loaded configuration
} else if (result instanceof AdaptyResult.Error) {
AdaptyError error = ((AdaptyResult.Error) result).getError();
// handle the error
}
});
```
| 参数 | 是否必填 | 描述 |
| :----------------------- | :------------- | :----------------------------------------------------------- |
| **paywall** | 必填 | 一个 `AdaptyPaywall` 对象，用于获取所需付费墙的控制器。 |
| **loadTimeout** | 默认值：5 秒 | 此值限制该方法的超时时间。如果达到超时，将返回缓存数据或本地备用数据。请注意，在极少数情况下，此方法的超时时间可能比 `loadTimeout` 中指定的时间稍长，因为该操作可能包含多个底层请求。 |
:::note
如果您使用多种语言，请了解如何添加[付费墙编辑工具本地化](add-paywall-locale-in-adapty-paywall-builder)以及如何正确使用语言代码，详见[此处](android-localizations-and-locale-codes)。
:::
加载完成后，[展示付费墙](android-present-paywalls)。
## 获取默认受众的付费墙以加快获取速度 \{#get-a-paywall-for-a-default-audience-to-fetch-it-faster\}
通常情况下，付费墙的获取几乎是即时的，您无需担心加速此过程。但是，当您拥有大量目标受众和付费墙，且用户的网络连接较弱时，获取付费墙可能需要比预期更长的时间。在这种情况下，您可能希望展示默认付费墙，以确保流畅的用户体验，而不是不展示任何付费墙。
为解决此问题，您可以使用 `getPaywallForDefaultAudience` 方法，该方法为**所有用户**目标受众获取指定版位的付费墙。但请务必了解，推荐的方式是使用 `getPaywall` 方法获取付费墙，详见上方[获取付费墙信息](#fetch-paywall-designed-with-paywall-builder)部分。
:::warning
为何我们推荐使用 `getPaywall`
`getPaywallForDefaultAudience` 方法存在一些重要缺点：
- **潜在的向后兼容性问题**：如果您需要为不同的应用版本（当前版本和未来版本）展示不同的付费墙，可能会面临挑战。您要么必须设计支持当前（旧版）版本的付费墙，要么接受使用当前（旧版）版本的用户可能遇到付费墙无法渲染的问题。
- **失去精准定向**：所有用户将看到为**所有用户**目标受众设计的同一付费墙，这意味着您将失去个性化定向能力（包括基于国家、营销归因或您自己的自定义属性）。
如果您愿意接受这些缺点以获得更快的付费墙获取速度，请按如下方式使用 `getPaywallForDefaultAudience` 方法。否则，请坚持使用[上述](#fetch-paywall-designed-with-paywall-builder)的 `getPaywall`。
:::
```kotlin showLineNumbers
Adapty.getPaywallForDefaultAudience("YOUR_PLACEMENT_ID", locale = "en") { result ->
when (result) {
is AdaptyResult.Success -> {
val paywall = result.value
// the requested paywall
}
is AdaptyResult.Error -> {
val error = result.error
// handle the error
}
}
}
```
```java showLineNumbers
Adapty.getPaywallForDefaultAudience("YOUR_PLACEMENT_ID", "en", result -> {
if (result instanceof AdaptyResult.Success) {
AdaptyPaywall paywall = ((AdaptyResult.Success) result).getValue();
// the requested paywall
} else if (result instanceof AdaptyResult.Error) {
AdaptyError error = ((AdaptyResult.Error) result).getError();
// handle the error
}
});
```
:::note
`getPaywallForDefaultAudience` 方法从 Android SDK 2.11.3 开始可用。
:::
| 参数 | 是否必填 | 描述 |
|---------|--------|-----------|
| **placementId** | 必填 | [版位](placements)的标识符。这是您在 Adapty 看板中创建版位时指定的值。 |
| **locale** | 可选
默认值：`en`
| [付费墙本地化](add-remote-config-locale)的标识符。该参数应为由一个或多个子标签组成的语言代码，子标签之间用减号（**-**）分隔。第一个子标签表示语言，第二个表示地区。
示例：`en` 表示英语，`pt-br` 表示巴西葡萄牙语。
有关语言代码及推荐使用方式的更多信息，请参阅[本地化与语言代码](localizations-and-locale-codes)。
|
| **fetchPolicy** | 默认值：`.reloadRevalidatingCacheData` | 默认情况下，SDK 将尝试从服务器加载数据，如果失败则返回缓存数据。我们推荐此选项，因为它可确保用户始终获取最新数据。
但是，如果您认为用户的网络连接不稳定，可以考虑使用 `.returnCacheDataElseLoad`，在缓存数据存在时返回缓存数据。在这种情况下，用户获取的数据可能不是最新的，但无论网络连接质量如何，都能获得更快的加载速度。缓存会定期更新，因此在会话期间使用缓存以避免网络请求是安全的。
请注意，缓存在应用重启后仍然保留，只有在重新安装应用或手动清理时才会清除。
|
## 自定义素材 \{#customize-assets\}
要自定义付费墙中的图片和视频，请实现自定义素材。
主图和视频具有预定义的 ID：`hero_image` 和 `hero_video`。在自定义素材包中，您通过这些 ID 定位相应元素并自定义其行为。
对于其他图片和视频，您需要在 Adapty 看板中[设置自定义 ID](custom-media)。
例如，您可以：
- 向部分用户展示不同的图片或视频。
- 在远程主图加载时展示本地预览图。
- 在播放视频前展示预览图。
:::important
要使用此功能，请将 Adapty Android SDK 更新至 3.7.0 或更高版本。
:::
以下是通过简单字典提供自定义素材的示例：
```kotlin showLineNumbers
val customAssets = AdaptyCustomAssets.of(
"hero_image" to
AdaptyCustomImageAsset.remote(
url = "https://example.com/image.jpg",
preview = AdaptyCustomImageAsset.file(
FileLocation.fromAsset("images/hero_image_preview.png"),
)
),
"hero_video" to
AdaptyCustomVideoAsset.file(
FileLocation.fromResId(requireContext(), R.raw.custom_video),
preview = AdaptyCustomImageAsset.file(
FileLocation.fromResId(requireContext(), R.drawable.video_preview),
),
),
)
val paywallView = AdaptyUI.getPaywallView(
activity,
viewConfiguration,
products,
eventListener,
insets,
customAssets,
)
```
:::note
如果未找到某个素材，付费墙将回退到其默认外观。
:::