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

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

Quy tắc và lưu ý

Xem Tải paywalls và sản phẩm để tham khảo tham số fetchPolicy và loadTimeout, và Placements để chọn đúng placement.

Tải trước các placement

preloadFlows lưu flow JSON vào bộ nhớ đệm trước — một request cho mỗi placement. Sau đó bạn sử dụng như bình thường: getFlow để lấy flow, getFlowConfiguration để lấy cấu hình view của nó.

fetchPolicy quyết định layer nào mà getFlow gọi sau sẽ đọc trước, không phải quyết định có thể truy cập cache hay không:

• ReturnCacheDataElseLoad đọc bản đã tải sẵn trước, chỉ kết nối mạng khi không có cache. ReturnCacheDataIfNotExpiredElseLoad(maxAgeMillis) hoạt động tương tự khi bản cache còn trẻ hơn maxAgeMillis.
• Mặc định là ReloadRevalidatingCacheData — ưu tiên kết nối mạng, chỉ dùng bản đã tải sẵn khi request thất bại hoặc hết thời gian chờ.

Việc tải trước đều có lợi trong cả hai trường hợp, nhưng theo cách khác nhau: chính sách ưu tiên cache loại bỏ hoàn toàn request, còn chính sách mặc định vẫn gửi request nhưng có sẵn bản dự phòng đã được làm ấm.

Dùng cách này khi bạn biết trước placement nào sẽ cần trong phiên nhưng chưa muốn hiển thị ngay — ví dụ, ngay sau khi activate và identify hoàn thành, cho flow đằng sau một nút mà người dùng chưa nhấn.

...

Adapty.preloadFlows(listOf("onboarding", "main_paywall"), loadTimeout = 5.seconds) { error ->
    if (error != null) {
        // at least one placement failed to preload
    }
}

// Later, when the user reaches the paywall:
Adapty.getFlow(
    "main_paywall",
    fetchPolicy = AdaptyPlacementFetchPolicy.ReturnCacheDataElseLoad,
) { result ->
    // ...
}

...

Adapty.preloadFlows(Arrays.asList("onboarding", "main_paywall"), TimeInterval.seconds(5), error -> {
    if (error != null) {
        // at least one placement failed to preload
    }
});

// Later, when the user reaches the paywall:
Adapty.getFlow("main_paywall", AdaptyPlacementFetchPolicy.ReturnCacheDataElseLoad, result -> {
    // ...
});

Tham số:

• placementIds (bắt buộc): các placement cần tải trước. Các ID trống và trùng lặp sẽ bị bỏ qua.
• loadTimeout (tùy chọn): timeout áp dụng cho từng placement trong batch, không phải cho toàn bộ batch. Mặc định là 5 giây, và các giá trị dưới 1 giây sẽ được nâng lên thành 1 giây.

Những điều cần lưu ý về hành vi:

• Callback chỉ được kích hoạt sau khi tất cả các placement đã được xử lý, và nó báo cáo các lỗi theo từng placement cùng nhau. Lỗi ở một placement không ảnh hưởng đến các placement khác.
• Nếu một placement bị timeout, gặp lỗi server, hoặc lỗi mạng, SDK sẽ chuyển sang dùng các biến thể dự phòng cho placement đó. Các lỗi khác được báo cáo nguyên trạng.
• Preloading chỉ làm ấm cache. Nó không trả về nội dung — bạn vẫn phải gọi getFlow để hiển thị.

Những gì preload bao gồm

Một flow hiển thị trên màn hình theo từng lớp. Preload bao gồm lớp đầu tiên, giống hệt như getFlow làm:

getFlowConfiguration chờ layout được tải về, nên lần đầu tiên yêu cầu một layout nhất định vẫn tốn một round trip dù đã preload trước. SDK sau đó lưu layout đó vào bộ nhớ đệm trên đĩa, bộ nhớ này tồn tại qua các lần khởi động lại ứng dụng và được đọc trước mọi lần gọi mạng, vì vậy chi phí chỉ xảy ra ở lần yêu cầu đầu tiên chứ không phải mỗi lần. Khi SDK đã có layout, nó bắt đầu cache ảnh độc lập với lần gọi: việc này không làm chặn màn hình, và không có callback hay lỗi nào thông báo khi hoàn tất.

Tìm hiểu placement nào gặp lỗi

Callback nhận về một AdaptyPreloadPlacementsError bao quát toàn bộ batch, với mã lỗi REQUEST_FAILED (2005). Để xem chi tiết từng lỗi riêng lẻ, hãy đọc thuộc tính preloadErrors — một map được đánh key theo placement ID:

Adapty.preloadFlows(listOf("onboarding", "main_paywall")) { error ->
    if (error is AdaptyPreloadPlacementsError) {
        error.preloadErrors.forEach { (placementId, placementError) ->
            // log or retry the individual placement
        }
    }
}

preloadErrors exists only on AdaptyPreloadPlacementsError, so confirm the type first — any other AdaptyError came from something other than a per-placement failure.

Bỏ qua phân khúc đối tượng

Để làm ấm cache mà không cần chờ phân khúc đối tượng, hãy dùng biến thể default-audience. Cách này không cần loadTimeout:

Adapty.preloadFlowsForDefaultAudience(listOf("main_paywall")) { error -> }

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 của màn hình đầu tiên ngay lập tức, hãy phục vụ nó từ app bundle thay thế. Đây là cách hay để tái sử dụng media bạn đã đóng gói sẵn, chẳng hạn như hình ảnh của một onboarding gốc hiện có.

1. Trong Flow & Paywall Builder, đặt ID media tùy chỉnh cho hình ảnh hoặc video. File bạn tải lên đó sẽ là file dự phòng.
2. Thêm file vào thư mục res/raw hoặc assets của ứng dụng.
3. Khi tạo flow view bằng getFlowView, truyền file đã đóng gói sẵn cho ID đó vào customAssets:

// "welcome_video" is the custom media ID set in the Flow & Paywall Builder
val bundledAssets = AdaptyCustomAssets.of(
    "welcome_video" to
            AdaptyCustomVideoAsset.file(
                FileLocation.fromResId(requireContext(), R.raw.welcome),
                preview = AdaptyCustomImageAsset.file(
                    FileLocation.fromResId(requireContext(), R.drawable.welcome_poster),
                ),
                resolution = AdaptyCustomVideoAsset.Resolution(width = 1080, height = 1920),
            ),
)

val flowView = AdaptyUI.getFlowView(
    activity,
    flowConfiguration,
    products,
    eventListener,
    insets,
    bundledAssets,
)

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

Media không được đóng gói vẫn hiển thị ngay lập tức: cấu hình view mang theo một bản sao độ phân giải thấp nhỏ của mỗi hình ảnh, bao gồm cả khung tĩnh của video, và hiển thị cho đến khi tệp đầy đủ được 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 (vùng nông thôn, phương tiện giao thông, khu vực bị ảnh hưởng bởi định tuyến):

• Đặt fetchPolicy thành AdaptyPlacementFetchPolicy.ReturnCacheDataElseLoad cho mọi lần tả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 paywall dự phòng khi hết thời gian chờ.
• Đừng chặn việc hiển thị flow khi chờ getProfile. Gọi getFlow độc lập để hồ sơ người dùng tải chậm không chặn giao diện.