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

Một lần tải paywall đáng tin cậy trên iOS cần đảm bảo ba điều: hiển thị nhanh, trả về đúng paywall theo đối tượng, và xử lý dự phòng tốt khi mạng chậm. Các quy tắc dưới đây bao gồm 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 giả định Adapty.activate() và Adapty.identify() đã hoàn thành. Xem Thứ tự gọi trong iOS SDK.

Quy tắc và những lỗi thường gặp

Làm điều này	Không làm điều này	Lý do
Fetch placement bạn sắp hiển thị, hoặc làm ấm cache bằng `preloadFlows` (SDK 4.1+).	Tự mình tạo các lệnh gọi `getFlow` đồng thời khi khởi chạy.	Một batch prefetch tự làm sẽ chặn main thread và gây ra màn hình đen. `preloadFlows` được xây dựng cho mục đích này và chia sẻ một ngân sách timeout chung cho toàn bộ batch.
Fetch `getPaywall` sau khi attribution đã có cơ hội resolve — ví dụ: 1–2 giây sau `activate` hoặc sau khi `onProfileUpdate` được kích hoạt.	Gọi `getPaywall` tại `App.init()`.	Attribution chưa được xử lý xong. Paywall 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ờ `getPaywall` vô thời hạn.	Không có timeout, người dùng với 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 tắt ứng dụng.

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 placements

Info

Các phương thức này khả dụng từ SDK phiên bản 4.1.

preloadFlows và preloadOnboardings tải các placement vào bộ nhớ cache của SDK trước. Khi gọi getFlow hoặc getOnboarding cho cùng một placement sau đó, kết quả sẽ được lấy từ cache thay vì từ mạng, giúp paywall hiển thị ngay mà không cần chờ đợi.

Sử dụng khi bạn biết trước session sẽ cần những placement nào nhưng chưa muốn hiển thị chúng ngay — ví dụ, ngay sau khi activate và identify hoàn tất, cho paywall ở sau nút mà người dùng chưa nhấn.

try await Adapty.preloadFlows(
    placementIds: ["onboarding", "main_paywall"],
    loadTimeout: 5
)

try await Adapty.preloadOnboardings(
    placementIds: ["intro"],
    locale: "en",
    loadTimeout: 5
)

Adapty.preloadFlows(placementIds: ["onboarding", "main_paywall"], loadTimeout: 5) { error in
    if let error {
        // at least one placement failed to preload
    }
}

Các tham số:

placementIds (bắt buộc): các placement cần tải trước. ID trống hoặc trùng lặp sẽ bị bỏ qua.
locale (tùy chọn, chỉ dùng cho preloadOnboardings): locale của onboarding cần lưu vào bộ nhớ đệm.
loadTimeout (tùy chọn): thời gian chờ tính bằng giây cho toàn bộ batch, không phải cho từng placement. 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.

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

Các phương thức chỉ throw sau khi đã thử tất cả các placement, và lỗi tổng hợp các thất bại theo từng placement. Lỗi ở một placement không dừng các placement khác.
Nếu một placement hết thời gian chờ hoặc thất bại do lỗi mạng, SDK sẽ dùng biến thể đối tượng mặc định cho placement đó. Các lỗi khác được báo cáo nguyên vẹn.
Nếu timeout kích hoạt trước khi hoàn tất việc lấy dữ liệu theo đối tượng, SDK vẫn thử biến thể đối tượng mặc định trong thời gian còn lại.
Preloading chỉ làm ấm cache. Nó không trả về nội dung — bạn vẫn cần gọi getFlow hoặc getOnboarding để hiển thị.

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

Lỗi được ném ra là một AdaptyError duy nhất bao gồm toàn bộ batch, với mã networkFailed (2002). Để xem các lỗi riêng lẻ, hãy đọc thuộc tính preloadErrors — một dictionary có khóa là placement ID:

do {
    try await Adapty.preloadFlows(placementIds: ["onboarding", "main_paywall"])
} catch {
    for (placementId, placementError) in error.preloadErrors ?? [:] {
        // log or retry the individual placement
    }
}

preloadErrors là nil đối với bất kỳ lỗi nào không đến từ lệnh gọi preload, vì vậy hãy xem giá trị nil là “không phải lỗi preload” thay vì “không có lỗi”.

Để làm ấm cache mà không cần chờ phân loại đối tượng, hãy sử dụng các biến thể đối tượng mặc định:

try await Adapty.preloadFlowsForDefaultAudience(placementIds: ["main_paywall"])
try await Adapty.preloadOnboardingsForDefaultAudience(placementIds: ["intro"])

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 công cộng, các vùng bị ảnh hưởng bởi định tuyến mạng):

Đặt fetchPolicy: .returnCacheDataElseLoad cho mọi lần tải 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 phương án dự phòng khi timeout xảy ra.
Không chặn việc hiển thị paywall vào getProfile(). Gọi getPaywall độc lập để một profile chậm không làm chặn giao diện.