Tối ưu hóa việc tải flow & paywall trong Kotlin Multiplatform SDK

Một lần tải flow hoặc paywall đáng tin cậy trên Kotlin Multiplatform cần đảm bảo ba điều: hiển thị nhanh, trả về biến thể đúng với đối tượng mục tiêu, và có phương án dự phòng khi mạng chậm. Các nguyên tắc dưới đây sẽ hướng dẫn bạn về thời điểm, bộ nhớ đệm và các mẫu dự phòng để đạt được điều đó.

Tip

Các quy tắc này yêu cầu Adapty.activate() và Adapty.identify() đã được giải quyết xong. Xem Thứ tự gọi trong SDK Kotlin Multiplatform.

Quy tắc và lưu ý

Nên làm	Không nên làm	Lý do
Fetch placement mà bạn sắp hiển thị.	Prefetch tất cả các placement đồng thời khi khởi động.	Prefetch hàng loạt làm chặn main thread và gây màn hình đen trong lúc burst.
Fetch `getFlow` sau khi attribution đã có cơ hội resolve — ví dụ, 1–2 giây sau `activate` hoặc sau khi `setOnProfileUpdatedListener` kích hoạt.	Gọi `getFlow` khi khởi động app.	Attribution chưa được ghi nhận. Flow sẽ resolve theo đối tượng mặc định và âm thầm bỏ qua các phân khúc cũng như cá nhân hóa ASA.
Đặt `loadTimeout` và cấu hình paywall dự phòng cho mỗi placement.	Chờ `getFlow` vô thời hạn.	Không có timeout, người dùng có kết nối kém sẽ thấy màn hình trắng cho đến khi mạng phục hồi — hoặc họ sẽ đóng app.

Xem Tải paywall và sản phẩm để tham khảo các tham số fetchPolicy và loadTimeout, và Placements để chọn placement phù hợp.

Hiển thị media màn hình đầu tiên từ app bundle

Một flow tải hình ảnh và video từ Adapty. Để hiển thị media ngay lập tức trên màn hình đầu tiên, hãy phục vụ chúng từ app bundle thay thế. Đây là cách tốt để tái sử dụng media mà bạn đã có sẵn trong app, chẳng hạn như hình ảnh của một onboarding gốc hiện có.

Trong Flow & Paywall Builder, đặt custom media ID cho ảnh hoặc video. File bạn upload ở đó sẽ là file dự phòng.
Thêm file vào tài nguyên ứng dụng, trong commonMain/composeResources/files/.
Khi tạo flow view, truyền file đã đóng gói cho ID đó vào customAssets:

// "welcome_video" is the custom media ID set in the Flow & Paywall Builder
val bundledAssets: Map<String, AdaptyCustomAsset> = mapOf(
    "welcome_video" to AdaptyCustomAsset.localVideoResource(
        path = Res.getUri("files/videos/welcome.mp4")
    ),
)

AdaptyUI.createFlowView(
    flow = flow,
    customAssets = bundledAssets,
).onSuccess { view ->
    view.present()
}.onError { error ->
    // handle the error
}

Các file đi kèm sẽ làm tăng dung lượng tải về của ứng dụng, vì vậy chỉ đóng gói các media mà người dùng nhìn thấy đầu tiên.

Nội dung media bạn không đóng gói vẫn hiển thị ngay lập tức: layout của flow bao gồm một bản sao độ phân giải thấp nhỏ của mỗi hình ảnh, kể cả khung tĩnh của video, và hiển thị bản đó cho đến khi file đầy đủ tải xong.

Để xem tài liệu tham khảo đầy đủ về customAssets, xem Tùy chỉnh assets.

Điều chỉnh cho kết nối kém

Đối với các thị trường có kết nối kém liên tục (khu vực nông thôn, phương tiện giao thông công cộng, khu vực bị ảnh hưởng bởi định tuyến):

Đặt fetchPolicy = AdaptyPaywallFetchPolicy.ReturnCacheDataElseLoad cho mọi lần fetch ngoại trừ lần đầu tiên.
Cấu hình paywall dự phòng cho mỗi placement trong Adapty dashboard.
Đặt loadTimeout từ 3–5 giây và chấp nhận fallback khi timeout kích hoạt.
Đừng chặn việc hiển thị flow khi chờ Adapty.getProfile(). Gọi getFlow độc lập để một profile chậm không làm chặn UI.