获取流程与付费墙 - iOS

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

获取流程/付费墙

如果你已通过 Flow Builder 或付费墙编辑工具设计了流程或付费墙，无需在移动端代码中手动编写渲染逻辑来向用户展示它。这类流程或付费墙本身已包含展示内容和展示方式。不过，你仍需通过版位获取其 ID 和视图配置，然后在移动端将其呈现出来。 为了确保最佳性能，请尽早获取流程或付费墙及其视图配置，以便在向用户展示之前有足够的时间下载图片。

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

do {
    let flow = try await Adapty.getFlow(placementId: "YOUR_PLACEMENT_ID")
    // 请求的流程/付费墙
} catch {
    // 处理错误
}

Adapty.getFlow(placementId: "YOUR_PLACEMENT_ID") { result in
    switch result {
        case let .success(flow):
            // 请求的流程/付费墙
        case let .failure(error):
            // 处理错误
    }
}

参数：

获取视图配置

获取流程或付费墙后，通过 flow.hasViewConfiguration 检查其是否包含视图配置。该标志用于区分版位在 Adapty 看板中的设计方式：

• true — 该版位使用 Flow Builder（流程）或 Paywall Builder（付费墙）设计，Adapty 会自动为你渲染 UI。请继续执行以下步骤来获取视图配置，并展示流程或付费墙。
• false — 该版位是不含 Builder UI 的自定义付费墙。 使用 getFlowConfiguration 方法加载视图配置。

guard flow.hasViewConfiguration else {
    // handle as remote config paywall
    return
}

let flowConfiguration = try await AdaptyUI.getFlowConfiguration(forFlow: flow)

参数：

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

通常情况下，流程和付费墙的获取速度几乎是即时的，无需担心性能问题。但如果你的版位和目标受众数量较多，而用户的网络状况又较差，获取流程或付费墙的时间可能会比预期更长。在这种情况下，你可能希望展示一个默认的流程或付费墙，以保证用户体验的流畅性，而不是让用户看到空白页面。 为了解决这个问题，你可以使用 getFlowForDefaultAudience 方法，该方法会获取指定版位中 All Users 目标受众的流程或付费墙。但请务必了解，推荐的做法是使用 getFlow 方法获取流程或付费墙，详情请参阅上方的获取付费墙信息部分。

Adapty.getFlowForDefaultAudience(placementId: "YOUR_PLACEMENT_ID") { result in
    switch result {
        case let .success(flow):
            // the requested flow
        case let .failure(error):
            // handle the error
    }
}

自定义资源

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

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

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

例如，你可以：

• 向部分用户展示不同的图片或视频。
• 在远程主图加载时，先展示本地预览图。
• 在视频播放前展示预览图。
• 提供视频的像素分辨率，以便播放器在视频加载前预留布局空间（宽高比 = width / height）。传入 nil 可跳过此项。

下面是一个通过简单字典提供自定义资源的示例：

let customAssets: [String: AdaptyCustomAsset] = [
    // Show a local image using a custom ID
    "custom_image": .image(
        .uiImage(value: UIImage(named: "image_name")!)
    ),

    // Show a local preview image while a remote main image is loading
    "hero_image": .image(
        .remote(
            url: URL(string: "https://example.com/image.jpg")!,
            preview: UIImage(named: "preview_image")
        )
    ),

    // Show a local video with a preview image and a known resolution
    "hero_video": .video(
        .file(
            url: Bundle.main.url(forResource: "custom_video", withExtension: "mp4")!,
            preview: .uiImage(value: UIImage(named: "video_preview")!),
            resolution: CGSize(width: 1080, height: 1920)
        )
    ),
]

let flowConfig = try await AdaptyUI.getFlowConfiguration(
    forFlow: flow,
    assetsResolver: customAssets
)

设置开发者定义的计时器

要在移动应用中使用自定义计时器，请创建一个遵循 AdaptyTimerResolver 协议的对象。该对象定义每个自定义计时器的渲染方式。如果您愿意，也可以直接使用 [String: Date] 字典，因为它已经符合该协议。以下是一个示例：

@MainActor
struct AdaptyTimerResolverImpl: AdaptyTimerResolver {
    func timerEndAtDate(for timerId: String) -> Date {
        switch timerId {
        case "CUSTOM_TIMER_6H":
            Date(timeIntervalSinceNow: 3600.0 * 6.0) // 6 hours
        case "CUSTOM_TIMER_NY":
            Calendar.current.date(from: DateComponents(year: 2025, month: 1, day: 1)) ?? Date(timeIntervalSinceNow: 3600.0)
        default:
            Date(timeIntervalSinceNow: 3600.0) // 1 hour
        }
    }
}

在此示例中，CUSTOM_TIMER_NY 和 CUSTOM_TIMER_6H 是你在 Adapty 看板中设置的开发者自定义计时器的 Timer ID。timerResolver 确保你的应用动态地为每个计时器更新正确的值。例如：

• CUSTOM_TIMER_NY：距离计时器结束（例如元旦）的剩余时间。
• CUSTOM_TIMER_6H：从用户打开付费墙时开始计算的 6 小时倒计时的剩余时间。

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

请注意，本文介绍的是通过付费墙编辑工具自定义的付费墙。如果你是手动实现付费墙，请参阅获取远程配置付费墙的付费墙和产品。

do {
    let paywall = try await Adapty.getPaywall("YOUR_PLACEMENT_ID")
    // the requested paywall
} catch {
    // handle the error
}

Adapty.getPaywall(placementId: "YOUR_PLACEMENT_ID", locale: "en") { result in
    switch result {
        case let .success(paywall):
            // the requested paywall
        case let .failure(error):
            // handle the error
    }
}

获取付费墙后，检查其是否包含视图配置——视图配置的存在表明该付费墙是通过付费墙编辑工具创建的。这将指导你如何展示付费墙。如果存在视图配置，则将其视为付费墙编辑工具付费墙；否则，将其作为远程配置付费墙处理。 使用 getPaywallConfiguration 方法加载视图配置。

guard paywall.hasViewConfiguration else {
    //  use your custom logic
    return
}

do {
    let paywallConfiguration = try await AdaptyUI.getPaywallConfiguration(
            forPaywall: paywall,
            products: products
    )
    // use loaded configuration
} catch {
    // handle the error
}

参数：

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

获取默认目标受众的付费墙以加速获取

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

要解决这个问题，你可以使用 getPaywallForDefaultAudience 方法，该方法会获取指定版位中针对 All Users 目标受众的付费墙。但请务必注意，推荐的方式仍然是使用 getPaywall 方法获取付费墙，详见上方的获取付费墙信息章节。

Adapty.getPaywallForDefaultAudience(placementId: "YOUR_PLACEMENT_ID", locale: "en") { result in
    switch result {
        case let .success(paywall):
            // the requested paywall
        case let .failure(error):
            // handle the error
    }
}

自定义资源

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

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

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

例如，你可以：

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

以下是通过简单字典提供自定义资源的示例：

let customAssets: [String: AdaptyCustomAsset] = [
    // 使用自定义 ID 显示本地图片
    "custom_image": .image(
        .uiImage(value: UIImage(named: "image_name")!)
    ),

    // 远程主图加载时显示本地预览图
    "hero_image": .image(
        .remote(
            url: URL(string: "https://example.com/image.jpg")!,
            preview: UIImage(named: "preview_image")
        )
    ),

    // 显示带预览图的本地视频
    "hero_video": .video(
        .file(
            url: Bundle.main.url(forResource: "custom_video", withExtension: "mp4")!,
            preview: .uiImage(value: UIImage(named: "video_preview")!)
        )
    ),
]

let paywallConfig = try await AdaptyUI.getPaywallConfiguration(
    forPaywall: paywall,
    assetsResolver: customAssets
)

设置开发者自定义计时器

要在移动应用中使用自定义计时器，需创建一个遵循 AdaptyTimerResolver 协议的对象。该对象定义了每个自定义计时器的渲染方式。如果你更喜欢，也可以直接使用 [String: Date] 字典，因为它已经符合该协议。以下是示例：

@MainActor
struct AdaptyTimerResolverImpl: AdaptyTimerResolver {
    func timerEndAtDate(for timerId: String) -> Date {
        switch timerId {
        case "CUSTOM_TIMER_6H":
            Date(timeIntervalSinceNow: 3600.0 * 6.0) // 6 hours
        case "CUSTOM_TIMER_NY":
            Calendar.current.date(from: DateComponents(year: 2025, month: 1, day: 1)) ?? Date(timeIntervalSinceNow: 3600.0)
        default:
            Date(timeIntervalSinceNow: 3600.0) // 1 hour
        }
    }
}

在此示例中，CUSTOM_TIMER_NY 和 CUSTOM_TIMER_6H 是你在 Adapty 看板中设置的开发者自定义计时器的 Timer ID。timerResolver 确保你的应用动态地为每个计时器更新正确的值。例如：

• CUSTOM_TIMER_NY：距离计时器结束时间（如元旦）的剩余时间。
• CUSTOM_TIMER_6H：用户打开付费墙后开始的 6 小时倒计时的剩余时间。