Lấy flows & paywalls - iOS

Sau khi bạn đã thiết kế flow hoặc paywall trong Paywall Builder, bạn có thể hiển thị nó trong ứng dụng di động của mình. Bước đầu tiên là lấy flow hoặc paywall được liên kết với placement và cấu hình view tương ứng như mô tả bên dưới.

Tải flow/paywall

Nếu bạn đã thiết kế một flow hoặc paywall bằng Flow Builder hoặc Paywall Builder, bạn không cần lo lắng về việc render nó trong code ứng dụng mobile để hiển thị cho người dùng. Flow hoặc paywall đó đã bao gồm cả nội dung cần hiển thị lẫn cách hiển thị. Tuy nhiên, bạn vẫn cần lấy ID của nó thông qua placement, cấu hình view, rồi mới trình bày nó trong ứng dụng mobile của bạn. Tải flow hoặc paywall và cấu hình view của nó càng sớm càng tốt — lý tưởng là trước khi hiển thị. Ngay khi bạn tải cấu hình view, SDK bắt đầu tải và cache hình ảnh trong nền. Tải càng sớm, các hình ảnh có càng nhiều thời gian để hoàn tất. Đến khi bạn hiển thị flow hoặc paywall, cấu hình và hình ảnh của nó đã có thể được cache sẵn sàng.

Để lấy flow hoặc paywall, sử dụng phương thức getFlow:

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

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

Tham số:

Lấy cấu hình giao diện

Sau khi lấy flow hoặc paywall, hãy kiểm tra xem nó có bao gồm cấu hình giao diện hay không thông qua flow.hasViewConfiguration. Cờ này cho biết cách placement được thiết kế trong Adapty Dashboard:

• true — placement được thiết kế trong Flow Builder (một flow) hoặc Paywall Builder (một paywall). Adapty sẽ tự động hiển thị giao diện cho bạn. Tiếp tục với các bước bên dưới để lấy cấu hình giao diện và hiển thị flow hoặc paywall.
• false — placement là một paywall tùy chỉnh không có giao diện Builder. Sử dụng phương thức getFlowConfiguration để tải cấu hình view.

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

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

Các tham số:

Lấy flow hoặc paywall cho đối tượng mặc định để tải nhanh hơn

Thông thường, flow và paywall được tải gần như ngay lập tức, nên bạn không cần lo lắng về việc tăng tốc quá trình này. Tuy nhiên, trong trường hợp bạn có nhiều đối tượng và placement, và người dùng của bạn có kết nối internet yếu, việc tải flow hoặc paywall có thể mất nhiều thời gian hơn mong muốn. Trong những tình huống như vậy, bạn có thể muốn hiển thị một flow hoặc paywall mặc định để đảm bảo trải nghiệm người dùng mượt mà thay vì không hiển thị gì cả. Để giải quyết vấn đề này, bạn có thể dùng phương thức getFlowForDefaultAudience, phương thức này lấy flow hoặc paywall của placement được chỉ định cho đối tượng All Users. Tuy nhiên, điều quan trọng cần hiểu là cách tiếp cận được khuyến nghị là lấy flow hoặc paywall bằng phương thức getFlow, như đã trình bày trong phần Lấy thông tin Paywall ở trên.

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

Tùy chỉnh assets

Để tùy chỉnh hình ảnh và video trong paywall/flow của bạn, hãy triển khai custom assets.

Hình ảnh hero và video có ID được định sẵn: hero_image và hero_video. Trong một custom asset bundle, bạn nhắm đến các phần tử này theo ID của chúng và tùy chỉnh hành vi của chúng.

Đối với các hình ảnh và video khác, bạn cần đặt ID tùy chỉnh trong Adapty dashboard.

Ví dụ, bạn có thể:

• Hiển thị hình ảnh hoặc video khác nhau cho một số người dùng.
• Hiển thị hình ảnh xem trước cục bộ trong khi hình ảnh chính từ xa đang tải.
• Hiển thị hình ảnh xem trước trước khi phát video.
• Cung cấp độ phân giải pixel của video để trình phát có thể dành sẵn không gian bố cục (tỷ lệ khung hình = width / height) trước khi video tải. Truyền nil để bỏ qua phần này.

Dưới đây là ví dụ về cách cung cấp các asset tùy chỉnh thông qua một dictionary đơn giản:

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
)

Thiết lập timer do lập trình viên định nghĩa

Để sử dụng timer tùy chỉnh trong ứng dụng, hãy tạo một object tuân theo protocol AdaptyTimerResolver. Object này định nghĩa cách hiển thị từng timer tùy chỉnh. Nếu muốn, bạn có thể dùng trực tiếp dictionary [String: Date] vì nó đã tương thích với protocol này. Dưới đây là ví dụ:

@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
        }
    }
}

Trong ví dụ này, CUSTOM_TIMER_NY và CUSTOM_TIMER_6H là các Timer ID của các timer do developer tự định nghĩa mà bạn đã thiết lập trong Adapty Dashboard. timerResolver đảm bảo ứng dụng của bạn cập nhật động từng timer với giá trị chính xác. Ví dụ:

• CUSTOM_TIMER_NY: Thời gian còn lại cho đến khi timer kết thúc, chẳng hạn như Năm Mới.
• CUSTOM_TIMER_6H: Thời gian còn lại trong khoảng 6 giờ bắt đầu từ khi người dùng mở paywall.

Sau khi bạn đã thiết kế phần hiển thị cho paywall của mình bằng Paywall Builder trong Adapty Dashboard, bạn có thể hiển thị nó trong ứng dụng di động. Bước đầu tiên là lấy paywall liên kết với placement và cấu hình giao diện của nó như mô tả bên dưới.

Lưu ý rằng chủ đề này đề cập đến các paywall được tùy chỉnh bằng Paywall Builder. Nếu bạn đang triển khai paywall theo cách thủ công, hãy tham khảo Lấy paywall và sản phẩm cho paywall Remote Config.

Tải paywall được thiết kế bằng Paywall Builder

Nếu bạn đã thiết kế paywall bằng Paywall Builder, bạn không cần lo lắng về việc render nó trong code ứng dụng để hiển thị cho người dùng. Paywall như vậy đã bao gồm cả nội dung hiển thị lẫn cách thức hiển thị. Tuy nhiên, bạn vẫn cần lấy ID của nó thông qua placement, cấu hình view, rồi mới trình bày nó trong ứng dụng. Để đảm bảo hiệu suất tối ưu, hãy lấy paywall và cấu hình hiển thị của nó càng sớm càng tốt, nhờ đó ảnh có đủ thời gian tải xuống trước khi hiển thị cho người dùng.

Để lấy paywall, sử dụng phương thức getPaywall:

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
    }
}

Tham số:

Lấy cấu hình hiển thị của paywall được thiết kế bằng Paywall Builder

Sau khi lấy paywall, hãy kiểm tra xem nó có chứa cấu hình hiển thị hay không — đây là dấu hiệu cho thấy paywall được tạo bằng Paywall Builder. Điều này sẽ giúp bạn biết cách hiển thị paywall. Nếu cấu hình hiển thị có mặt, hãy xử lý nó như một paywall Paywall Builder; nếu không, xử lý nó như một paywall Remote Config. Sử dụng phương thức getPaywallConfiguration để tải cấu hình view.

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
}

Tham số:

Sau khi tải xong, hãy hiển thị paywall.

Lấy paywall cho đối tượng mặc định để tải nhanh hơn

Thông thường, paywall được tải gần như ngay lập tức, nên bạn không cần lo lắng về việc tối ưu tốc độ. Tuy nhiên, trong trường hợp bạn có nhiều đối tượng và paywall, hoặc người dùng đang dùng kết nối internet yếu, việc tải paywall có thể mất nhiều thời gian hơn mong muốn. Trong những tình huống đó, bạn có thể muốn hiển thị paywall mặc định để đảm bảo trải nghiệm người dùng mượt mà thay vì không hiển thị paywall nào cả. Để giải quyết vấn đề này, bạn có thể sử dụng phương thức getPaywallForDefaultAudience, phương thức này sẽ lấy paywall của placement đã chỉ định cho đối tượng All Users. Tuy nhiên, điều quan trọng cần hiểu là phương pháp được khuyến nghị vẫn là lấy paywall qua phương thức getPaywall, như đã trình bày chi tiết trong phần Lấy thông tin Paywall ở trên.

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
    }
}

Tùy chỉnh assets

Để tùy chỉnh hình ảnh và video trong paywall của bạn, hãy triển khai custom assets.

Hero image và video có ID được định sẵn: hero_image và hero_video. Trong một custom asset bundle, bạn nhắm tới các phần tử này bằng ID của chúng và tùy chỉnh hành vi của chúng.

Đối với các hình ảnh và video khác, bạn cần đặt ID tùy chỉnh trong Adapty dashboard.

Ví dụ, bạn có thể:

• Hiển thị hình ảnh hoặc video khác cho một số người dùng.
• Hiển thị ảnh xem trước cục bộ trong khi hình ảnh chính từ xa đang tải.
• Hiển thị ảnh xem trước trước khi phát video.

Đây là ví dụ về cách bạn có thể cung cấp custom assets thông qua một dictionary đơn giản:

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
    "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
)

Thiết lập timer do developer định nghĩa

Để sử dụng custom timer trong ứng dụng mobile, hãy tạo một object tuân theo protocol AdaptyTimerResolver. Object này xác định cách mỗi custom timer sẽ được hiển thị. Nếu muốn, bạn có thể dùng trực tiếp dictionary [String: Date], vì nó đã tuân thủ protocol này. Dưới đây là ví dụ:

@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
        }
    }
}

Trong ví dụ này, CUSTOM_TIMER_NY và CUSTOM_TIMER_6H là Timer ID của các timer do developer tự định nghĩa, được thiết lập trong Adapty Dashboard. timerResolver đảm bảo ứng dụng của bạn cập nhật động từng timer với giá trị chính xác. Ví dụ:

• CUSTOM_TIMER_NY: Thời gian còn lại cho đến khi timer kết thúc, chẳng hạn như ngày Tết Dương lịch.
• CUSTOM_TIMER_6H: Thời gian còn lại trong khoảng 6 giờ bắt đầu từ khi người dùng mở paywall.