Tối ưu hóa việc tải flow & paywall trong Flutter SDK
Một lần tải flow hoặc paywall đáng tin cậy trên Flutter 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à dự phòng hợp lý khi mạng chậm. Các quy tắc dưới đây bao gồm các mẫu về thời điểm, bộ nhớ đệm và dự phòng để đạt được điều đó.
Các quy tắc này giả định rằng Adapty().activate() và Adapty().identify() đã hoàn tất. Xem Thứ tự gọi trong Flutter SDK.
Quy tắc và lưu ý
| Làm điều này | Đừng làm thế này | Lý do |
|---|---|---|
Tải placement bạn sắp hiển thị, hoặc làm ấm cache bằng preloadFlows (SDK 4.3.0+). | Tự tạo nhiều lời gọi getFlow đồng thời khi khởi chạy. | Một lần prefetch thủ công sẽ chặn main thread và gây màn hình đen. preloadFlows được thiết kế cho mục đích này và gửi toàn bộ batch đến native SDK trong một lần gọi. |
Gọi getFlow sau khi attribution đã có cơ hội resolve — ví dụ, 1–2 giây sau activate hoặc sau khi didUpdateProfileStream kích hoạt. | Gọi getFlow trong main() trước runApp. | Attribution chưa được xử lý xong. Flow sẽ resolve theo đối tượng mặc định và âm thầm bỏ qua các phân khúc và 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. | Nếu 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ản hồi — hoặc đóng ứng dụng. |
Xem Tải paywall tùy chỉnh và sản phẩm để tham khảo thông số fetchPolicy và loadTimeout, và Placements để chọn placement phù hợp.
Tải trước các placement
preloadFlows và preloadFlowsForDefaultAudience khả dụng từ SDK phiên bản 4.3.0 trở lên.
preloadFlows lưu JSON của flow vào bộ nhớ đệm trước. Sau đó bạn sử dụng như bình thường: getFlow để lấy flow, createFlowView để tạo view của nó.
fetchPolicy quyết định lớp nào mà getFlow được gọi sau sẽ đọc trước, chứ không phải quyết định xem nó có thể truy cập bộ nhớ đệm hay không:
AdaptyFlowFetchPolicy.returnCacheDataElseLoadđọc bản sao đã được tải trước, chỉ gọi mạng khi không có gì trong cache.AdaptyFlowFetchPolicy.returnCacheDataIfNotExpiredElseLoad(maxAge)hoạt động tương tự miễn là bản sao còn trẻ hơnmaxAge.- Mặc định là
AdaptyFlowFetchPolicy.reloadRevalidatingCacheData, ưu tiên gọi mạng trước và dùng bản sao đã được tải trước khi yêu cầu thất bại hoặc hết thời gian chờ.
Việc tải trước sẽ có lợi theo cả hai hướng, nhưng khác nhau: chính sách ưu tiên cache sẽ loại bỏ request, còn chính sách mặc định giữ lại request nhưng có thêm bản sao đã warm để dự phòng. Trên thiết bị test, getFlow bỏ qua cache với mọi chính sách và chỉ sử dụng bản sao đã tải trước nếu request mạng thất bại.
Dùng tính năng này khi bạn biết trước những 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 nằm sau một nút mà người dùng chưa nhấn vào.
try {
await Adapty().preloadFlows(
placementIds: ['onboarding', 'main_paywall'],
loadTimeout: const Duration(seconds: 5),
);
} on AdaptyError catch (adaptyError) {
// at least one placement failed to preload
}
// Later, when the user reaches the paywall:
final flow = await Adapty().getFlow(
placementId: 'main_paywall',
fetchPolicy: AdaptyFlowFetchPolicy.returnCacheDataElseLoad,
);
Tham số:
placementIds(bắt buộc): các placement cần tải trước.loadTimeout(tùy chọn): thời gian chờ tải trước cho các flow theo đối tượng mục tiêu. Mặc định là 5 giây, các giá trị dưới 1 giây sẽ được nâng lên 1 giây. Khi hết thời gian chờ, SDK có thể tải các flow cho đối tượng mặc định thay thế.
Những điều cần lưu ý về cách hoạt động:
- Lệnh gọi chỉ thất bại sau khi tất cả các placement đã được thử, với một
AdaptyErrorduy nhất bao gồm tất cả các placement thất bại. Việc một placement thất bại không làm dừng các placement khác, và những placement đã tải thành công vẫn được lưu trong cache. - Preloading luôn gọi lên mạng: nó không có
fetchPolicyriêng. - Preloading chỉ làm nóng cache. Nó không trả về nội dung — bạn vẫn cần gọi
getFlowđể hiển thị.
Nội dung 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 thực hiện:
| Layer | Fetched by | Warmed by a preload |
|---|---|---|
| Flow JSON — the chosen variation, its product IDs, and the remote config | getFlow | Yes |
| UI layout — the screen’s structure, styling, and text | createFlowView | No |
| Images, including the still frame that stands in for a video element | createFlowView, in the background | No |
| Products | createFlowView or getPaywallProducts | No |
| Video files | The system player, as the screen renders | Not cached by the SDK |
Vì vậy, lần createFlowView đầu tiên cho một layout nhất định vẫn tốn một lượt round trip sau khi preload. SDK native sau đó lưu layout đó vào bộ nhớ cache trên đĩa, tồn tại qua các lần khởi động lại ứng dụng, nên chi phí chỉ rơi vào lần yêu cầu đầu tiên chứ không phải mỗi lần.
Bỏ qua phân khúc đối tượng
Để làm nóng bộ nhớ 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 timeout:
await Adapty().preloadFlowsForDefaultAudience(placementIds: ['main_paywall']);
Lệnh getFlowForDefaultAudience gọi sau sẽ đọc bản sao đó theo cách getFlow đọc bản sao từ preloadFlows.
Hiển thị media màn hình đầu 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ụ chúng từ app bundle thay thế. Đây là cách tốt để tái sử dụng media bạn đã có sẵn trong ứng dụng, chẳng hạn như hình ảnh của một onboarding native hiện có.
- Trong Flow & Paywall Builder, đặt custom media ID cho hình ảnh hoặc video. File bạn tải lên đó sẽ được dùng làm fallback.
- Thêm file vào assets Flutter và khai báo nó trong mục
assetscủapubspec.yaml. - 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
final bundledAssets = {
'welcome_video': AdaptyCustomAsset.localVideoAsset(
assetId: 'assets/videos/welcome.mp4',
),
};
try {
final view = await AdaptyUI().createFlowView(
flow: flow,
customAssets: bundledAssets,
);
} on AdaptyError catch (e) {
// handle the error
}
Các file được nhúng sẵn sẽ làm tăng dung lượng tải về của ứng dụng, vì vậy chỉ nhúng những media mà người dùng nhìn thấy đầu tiên.
Các media bạn không đóng gói sẵn 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 của từng hình ảnh, kể cả frame tĩnh của video, và hiển thị bản đó cho đến khi file đầy đủ tải xong.
Để tham khảo đầy đủ về customAssets, xem Tùy chỉnh assets.
Tối ưu 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, vùng bị ảnh hưởng bởi định tuyến mạng):
- Đặt
fetchPolicy: AdaptyFlowFetchPolicy.returnCacheDataElseLoadcho 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 trên Adapty Dashboard.
- Đặt
loadTimeouttừ 3–5 giây và chấp nhận dùng fallback khi timeout xảy ra. - Đừng chặn việc hiển thị flow vì
getProfile(). GọigetFlowđộc lập để một profile tải chậm không làm tắc nghẽn giao diện.