使用 iOS SDK 展示自定义元素
当包含自定义元素的页面打开时,Adapty SDK 会将该元素的 Type 和 ID 传递给应用代码中的解析器。解析器返回以下内容之一:
- 与 Type 和 ID 匹配的视图:用户将看到原生 SwiftUI 视图,例如 Lottie 动画、交互式数据图表或摄像头预览。
- 无视图:用户将看到备用内容,即 Flow & Paywall Builder 中自定义元素内的内容。
如果用户使用的是旧版本的应用——也就是完全没有解析器的版本——他们仍然会看到备用内容。因此,你可以在发布应用之前先发布流程。
开始之前
你需要:
- Adapty iOS SDK 4.4 或更高版本:旧版本会为每个自定义元素显示备用内容。
- 原生 iOS 应用:Flutter 等跨平台框架的 Adapty SDK 会为每个自定义元素显示备用内容。
- 自定义元素的命名规范:为每个原生视图指定一个 Type,例如
lottie_animation。Type 中只能使用小写字母、数字和下划线。若要区分相同 Type 的自定义元素,可为每个元素指定一个 ID,例如welcome_wave。代码中的 Type 和 ID 必须与流程与付费墙编辑工具中的配置保持一致。
为自定义元素创建视图
为每种 Type 创建一个原生 SwiftUI 视图,或复用应用中已有的视图。以下是 lottie_animation Type 的视图示例,用于播放 Lottie 动画:
struct LottieElementView: View {
let animation: LottieAnimation?
var body: some View {
LottieView(animation: animation)
.resizable()
.looping()
}
}
查看要求与最佳实践
- 尺寸:
- 内边距与对齐:确保原生视图适配你在 Flow 与付费墙编辑工具中为其分配的容器,并留出内边距。如果视图未能填满整个区域,默认会显示在该区域的左上角。若要移动它,请在自定义元素的 Layout 部分更改对齐方式。
- 自适应高度:如果自定义元素的高度设置为 Hug,会自动拉伸填满可用空间的视图(如地图)将会折叠。请为自定义元素设置固定高度。
- 流程操作:原生视图无法触发流程操作,例如跳转到下一个屏幕。请将导航按钮、购买按钮及其他带有流程操作的按钮放在自定义元素之外。
- 可选元素:请将自定义元素放在产品卡片及其他可选元素之外。当选中状态改变时,原生视图可能会丢失其状态。
- 导航处理:当用户跳转到下一个屏幕时,SwiftUI 会执行原生视图的
onDisappear操作。在此操作中,请停止视图启动的任务,例如相机会话、播放器和位置更新。对于异步任务,请使用.task:视图消失时 SwiftUI 会自动取消它。当用户返回时,SDK 会再次调用解析器,SwiftUI 也会重置视图状态。 - UIKit 视图:请使用
UIViewRepresentable进行包装。
编写解析器以匹配自定义元素和视图
要编写解析器,需让某个类型遵循 AdaptyUICustomElementsResolver 协议,并实现 view(forType:id:context:) 方法。
对于 lottie_animation 类型,以下解析器会返回 LottieElementView。其中 ID 指定的是应用包中的动画文件名,例如 welcome_wave:
struct CustomElementsResolver: AdaptyUICustomElementsResolver {
func view(
forType type: String,
id: String,
context: AdaptyUICustomElementContext
) -> AnyView? {
switch type {
case "lottie_animation":
// the ID names the animation file, such as welcome_wave.json
guard let animation = LottieAnimation.named(id) else {
return nil // no file for this ID: show the fallback
}
return AnyView(LottieElementView(animation: animation))
default:
return nil
}
}
}
在 default 分支中返回 nil。如果你在应用发布后添加了带有新 Type 的自定义元素,已发布版本的用户将看到其备用内容。
解析器有以下要求:
- 网络数据与播放器:将网络数据和播放器保存在原生视图的状态中,而非解析器中。SDK 在屏幕打开期间会多次调用解析器,例如在产品加载或购买开始时。解析器中的代码每次调用时都会重新执行,因此网络请求会重复发起,播放器也会从头开始。SwiftUI 会在多次调用之间保持原生视图的状态,所以数据只加载一次,播放器也能持续播放。请在
.task或@StateObject中创建播放器、会话和网络请求,而不要在@State属性的初始值中创建。Swift 每次解析器创建视图时都会重新求值该初始值。 - 每个自定义元素对应一个原生视图:部分原生视图在屏幕打开后会发生变化,例如数据加载完成或用户点击时。请在视图的
body中实现这些逻辑,而非在解析器中。如果解析器为同一个自定义元素返回不同的视图,SwiftUI 会重置该视图的状态。 - 应用数据:将持有数据的应用对象(例如带有每日连续登录的
ObservableObject)存储在解析器的属性中,将该对象传递给原生视图,并在视图中使用@ObservedObject观察它。复制到解析器中的值(例如连续登录天数)会保持创建解析器时的状态不变。不要为此数据使用环境对象:在 UIKit 流程控制器中,原生视图无法接收到应用的 SwiftUI 环境。
设置备用内容的显示条件
如需在自定义元素为空时向用户展示备用内容,请在以下情况下返回 nil:
- 无内容可渲染——所需的动画文件或数据文件缺失。
- 无数据可处理——用户跳过了某道测验题,导致数据不完整。
- 访问被禁止——权限被拒绝,视图无法访问相应资源。
例如,resolver 中的 guard 语句会在动画文件缺失时返回 nil。
对于权限请求,仅当用户在屏幕打开之前已明确拒绝时,才返回 nil。如果用户尚未响应权限请求,请返回原生视图而非 nil,并在该视图内请求权限。例如,在在流程中的地图上显示附近地点中,iOS 会在地图出现时弹出位置访问提示。一旦用户授予权限,原生视图即可立即显示地图。如果在用户响应之前就返回 nil,则即使用户已授予权限,备用内容也会保持显示,直到 SDK 再次调用 resolver 为止。
将解析器传递给 SDK
首先配置一个全局解析器。SDK 会在每个没有专属解析器的流程中调用它。用户无需更新应用,即可在新流程和 A/B 测试中看到你的原生视图。这些视图仍会为每位用户显示其专属数据(例如每日连续打卡记录),因为它们会直接从你的应用中读取该数据。
当流程需要应用在打开该流程时才具备的数据时,可为其附加一个解析器。例如,付费墙显示用户在前一个流程中输入的体重,或预览用户想要导出的文档。你也可以为某个流程附加解析器,以便在该流程中为某个 Type 显示不同的视图。
设置全局解析器
如需在所有流程中使用解析器,请在应用启动时调用一次 AdaptyUI.setCustomElementsResolver(_:):
// keep this instance: a resolver for one flow can reuse it
@MainActor let customElementsResolver = CustomElementsResolver()
AdaptyUI.setCustomElementsResolver(customElementsResolver)
更简单但功能有限的替代方案是传入一个以类型为键的 [String: AdaptyUICustomElementBuilder] 字典。这种方式代码量更少,但无法为备用内容设置条件。
AdaptyUI.setCustomElementsResolver([
"lottie_animation": .init { _, id, _ in LottieElementView(animation: .named(id)) },
])将解析器附加到单个流程
附加到某个流程的解析器会替换该流程中的全局解析器。传递给该解析器的值在你获取流程配置时保持不变。若要显示新值,请重新获取配置。
要在此流程中保留全局视图,请将全局解析器传入该解析器,并对其他 Types 和 IDs 调用全局解析器。以下解析器会预览用户想要导出的文档,并对所有其他自定义元素调用全局解析器:
struct ExportPaywallResolver: AdaptyUICustomElementsResolver {
let document: Document // the document that the user wants to export
let appWideResolver: any AdaptyUICustomElementsResolver
func view(
forType type: String,
id: String,
context: AdaptyUICustomElementContext
) -> AnyView? {
if type == "document_preview" {
return AnyView(DocumentPreview(document: document))
}
// other Types: the views of the app-wide resolver
return appWideResolver.view(forType: type, id: id, context: context)
}
}
在获取流程配置时,将解析器附加到流程:
func showExportPaywall(flow: AdaptyFlow, document: Document) async {
do {
let flowConfiguration = try await AdaptyUI.getFlowConfiguration(
forFlow: flow,
customElementsResolver: ExportPaywallResolver(
document: document,
appWideResolver: customElementsResolver // the instance that you set app-wide
)
)
// present the flow
} catch {
// handle the error
}
}
如果你使用字典而非解析器,请合并这两个字典,并将结果附加到流程中:appWideViews.merging(flowViews) { _, flowView in flowView }。对于同时存在于两个字典中的类型,此代码会保留当前流程的视图。
在设备上测试
流程与付费墙编辑工具无法运行你的应用代码,因此其画布只会显示备用内容。原生视图中的错误可能导致应用崩溃。在发布应用之前,请在设备上测试每一个包含自定义元素的页面:
-
若要查看每个流程的最新发布版本而非缓存版本,请将设备注册为测试设备。
-
在设备上运行包含解析器的构建版本。打开每个包含自定义元素的页面,确认原生视图已正常显示并与自定义元素匹配。如果视图支持滚动或拖拽手势,请一并测试。
-
如果显示的是备用内容而非原生视图,请在 Xcode 控制台中查找以下警告:
custom element <type>:<id> is not served by a resolver。然后确认以下几点:- 警告中的 Type 和 ID 与代码中的完全一致,包括大小写。
- 应用拥有该视图所需的文件、数据或权限。
- 应用在包含自定义元素的页面打开之前,已完成全局解析器的设置。
- 若已为该流程附加解析器,请确认其能针对对应的 Type 和 ID 返回视图。
如果警告未出现,请确认应用使用的是 Adapty iOS SDK 4.4 或更高版本,并且
Adapty.logLevel未设置为.error。 -
若要预览备用付费墙,请将 Type 返回值设置为
nil,然后重新打开该页面。
示例
每个示例都展示了编辑工具中的配置方式和应用代码:
- 使用 Lottie 动画展示用户进度:一个随连续打卡天数增长而填充的圆环。
- 在付费墙中展示可交互的体重目标图表:一个体重目标图表,位于用户引导流程之后的付费墙流程中。
- 在流程中显示附近地点的地图:展示每位用户附近健身中心的地图。