使用 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)
Tip

更简单但功能有限的替代方案是传入一个以类型为键的 [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 }。对于同时存在于两个字典中的类型,此代码会保留当前流程的视图。

在设备上测试

流程与付费墙编辑工具无法运行你的应用代码,因此其画布只会显示备用内容。原生视图中的错误可能导致应用崩溃。在发布应用之前,请在设备上测试每一个包含自定义元素的页面:

  1. 若要查看每个流程的最新发布版本而非缓存版本,请将设备注册为测试设备。

  2. 在设备上运行包含解析器的构建版本。打开每个包含自定义元素的页面,确认原生视图已正常显示并与自定义元素匹配。如果视图支持滚动或拖拽手势,请一并测试。

  3. 如果显示的是备用内容而非原生视图,请在 Xcode 控制台中查找以下警告:custom element <type>:<id> is not served by a resolver。然后确认以下几点:

    • 警告中的 Type 和 ID 与代码中的完全一致,包括大小写。
    • 应用拥有该视图所需的文件、数据或权限。
    • 应用在包含自定义元素的页面打开之前,已完成全局解析器的设置。
    • 若已为该流程附加解析器,请确认其能针对对应的 Type 和 ID 返回视图。

    如果警告未出现,请确认应用使用的是 Adapty iOS SDK 4.4 或更高版本,并且 Adapty.logLevel 未设置为 .error。

  4. 若要预览备用付费墙,请将 Type 返回值设置为 nil,然后重新打开该页面。

示例

每个示例都展示了编辑工具中的配置方式和应用代码: