Lấy danh sách onboarding trong Kotlin Multiplatform SDK

Onboardings đã bị deprecated trong SDK v4 và sẽ bị xóa trong một bản phát hành tương lai. Chúng không còn nhận được các bản sửa lỗi hay cải tiến nữa. Hãy sử dụng flows thay thế: không giống như onboardings chạy bên trong WebView, flows render trực tiếp trên thiết bị — mang lại animation mượt mà hơn, giao diện native nhất quán, thời gian tải nhanh hơn và không phụ thuộc vào WebView runtime. Xem Lấy flows & paywalls và Hiển thị flows & paywalls để bắt đầu.

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

Trước khi bắt đầu, hãy đảm bảo rằng:

Bạn đã cài đặt Adapty Kotlin Multiplatform SDK phiên bản 3.15.0 trở lên.
Bạn đã tạo một onboarding.
Bạn đã thêm onboarding vào một placement.

Tải onboarding

Khi bạn tạo một onboarding bằng trình tạo no-code của chúng tôi, nó được lưu trữ dưới dạng một container chứa cấu hình mà ứng dụng cần tải về và hiển thị. Container này quản lý toàn bộ trải nghiệm — nội dung hiển thị, cách trình bày, và cách xử lý các tương tác của người dùng (như câu trả lời quiz hoặc dữ liệu nhập từ biểu mẫu). Container cũng tự động theo dõi các sự kiện analytics, nên bạn không cần tự triển khai tính năng theo dõi lượt xem riêng.

Để đạt hiệu suất tốt nhất, hãy tải cấu hình onboarding sớm để ảnh có đủ thời gian tải xuống trước khi hiển thị cho người dùng.

Để lấy một onboarding, hãy sử dụng phương thức getOnboarding:


Adapty.getOnboarding(
    placementId = "YOUR_PLACEMENT_ID",
    locale = "en",
    fetchPolicy = AdaptyPaywallFetchPolicy.Default,
    loadTimeout = 5.seconds
).onSuccess { paywall ->
    // the requested paywall
}.onError { error ->
    // handle the error
}

Tham số:

Tham số	Bắt buộc	Mô tả
placementId	bắt buộc	Định danh của Placement mong muốn. Đây là giá trị bạn đã chỉ định khi tạo placement trong Adapty Dashboard.
locale	tùy chọn mặc định: `en`	Định danh của bản địa hóa onboarding. Tham số này phải là mã ngôn ngữ gồm một hoặc hai thẻ con được phân tách bằng ký tự dấu trừ (-). Thẻ con đầu tiên đại diện cho ngôn ngữ, thẻ con thứ hai đại diện cho vùng. Ví dụ: `en` nghĩa là tiếng Anh, `pt-br` đại diện cho tiếng Bồ Đào Nha (Brazil).
fetchPolicy	mặc định: `.reloadRevalidatingCacheData`	Theo mặc định, SDK sẽ cố tải dữ liệu từ máy chủ và trả về dữ liệu đã lưu trong cache nếu gặp lỗi. Chúng tôi khuyến nghị tùy chọn này vì nó đảm bảo người dùng luôn nhận được dữ liệu mới nhất. Tuy nhiên, nếu bạn cho rằng người dùng của mình thường xuyên gặp tình trạng mạng không ổn định, hãy cân nhắc dùng `.returnCacheDataElseLoad` để trả về dữ liệu cache nếu có. Trong trường hợp này, người dùng có thể không nhận được dữ liệu mới nhất tuyệt đối, nhưng sẽ có thời gian tải nhanh hơn bất kể kết nối mạng ra sao. Cache được cập nhật thường xuyên, nên việc sử dụng trong phiên làm việc để tránh các yêu cầu mạng là hoàn toàn an toàn. Lưu ý rằng cache vẫn được giữ nguyên khi khởi động lại ứng dụng và chỉ bị xóa khi cài đặt lại ứng dụng hoặc thực hiện dọn dẹp thủ công. Adapty SDK lưu trữ các onboarding cục bộ theo hai lớp: cache được cập nhật thường xuyên như mô tả ở trên và các onboarding dự phòng. Chúng tôi cũng sử dụng CDN để tải onboarding nhanh hơn và một máy chủ dự phòng độc lập trong trường hợp CDN không thể truy cập. Hệ thống này được thiết kế để đảm bảo bạn luôn nhận được phiên bản mới nhất của các onboarding, đồng thời đảm bảo độ tin cậy ngay cả khi kết nối mạng kém.
loadTimeout	mặc định: 5 giây	Giá trị này giới hạn thời gian chờ cho phương thức này. Nếu hết thời gian chờ, dữ liệu cache hoặc fallback cục bộ sẽ được trả về. Lưu ý rằng trong một số trường hợp hiếm gặp, phương thức này có thể hết thời gian chờ muộn hơn một chút so với giá trị đã chỉ định trong `loadTimeout`, do thao tác có thể bao gồm nhiều yêu cầu khác nhau bên dưới.

Tham số phản hồi

Tham số	Mô tả
Onboarding	Một đối tượng `AdaptyOnboarding` bao gồm: mã định danh và cấu hình onboarding, Remote Config, cùng một số thuộc tính khác.

Tăng tốc độ tải onboarding với onboarding dành cho đối tượng mặc định

Thông thường, onboarding đượ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à onboarding, mà người dùng lại có kết nối internet yếu, việc tải onboarding 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 onboarding mặc định để đảm bảo trải nghiệm người dùng mượt mà thay vì không hiển thị onboarding nào cả.

Để giải quyết vấn đề này, bạn có thể sử dụng phương thức getOnboardingForDefaultAudience, phương thức này tải onboarding 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à tải onboarding bằng phương thức getOnboarding, như đã mô tả chi tiết trong phần Fetch Onboarding ở trên.

Hãy cân nhắc sử dụng getOnboarding thay vì getOnboardingForDefaultAudience, vì phương thức sau có những hạn chế quan trọng:

Vấn đề tương thích: Có thể gây ra sự cố khi hỗ trợ nhiều phiên bản app, đòi hỏi thiết kế tương thích ngược hoặc chấp nhận rằng các phiên bản cũ có thể hiển thị không đúng.
Không có cá nhân hóa: Chỉ hiển thị nội dung cho đối tượng “All Users”, loại bỏ khả năng nhắm mục tiêu dựa trên quốc gia, attribution, hoặc thuộc tính tùy chỉnh.

Nếu tốc độ tải nhanh hơn vượt trội so với những hạn chế này trong trường hợp của bạn, hãy sử dụng getOnboardingForDefaultAudience như hướng dẫn bên dưới. Ngược lại, hãy dùng getOnboarding như đã mô tả ở trên.


Adapty.getOnboardingForDefaultAudience(
    placementId = "YOUR_PLACEMENT_ID",
    locale = "en",
    fetchPolicy = AdaptyPaywallFetchPolicy.Default,
).onSuccess { paywall ->
    // the requested paywall
}.onError { error ->
    // handle the error
}

Tham số:

Tham số Bắt buộc Mô tả

placementId bắt buộc Mã định danh của Placement mong muốn. Đây là giá trị bạn đã chỉ định khi tạo placement trong Adapty Dashboard.

Tham số	Bắt buộc	Mô tả
placementId	bắt buộc	Mã định danh của Placement mong muốn. Đây là giá trị bạn đã chỉ định khi tạo placement trong Adapty Dashboard.
locale	tùy chọn mặc định: `en`	Mã định danh của bản dịch onboarding. Tham số này cần là mã ngôn ngữ gồm một hoặc hai thẻ con được phân tách bằng ký tự dấu trừ (-). Thẻ con đầu tiên là cho ngôn ngữ, thẻ con thứ hai là cho vùng. Ví dụ: `en` là tiếng Anh, `pt-br` là tiếng Bồ Đào Nha (Brazil).
fetchPolicy	mặc định: `.reloadRevalidatingCacheData`	Theo mặc định, SDK sẽ cố tải dữ liệu từ máy chủ và trả về dữ liệu đã cache nếu xảy ra lỗi. Chúng tôi khuyên dùng tùy chọn này vì nó đảm bảo người dùng luôn nhận được dữ liệu mới nhất. Tuy nhiên, nếu bạn cho rằng người dùng thường gặp kết nối internet không ổn định, hãy cân nhắc dùng `.returnCacheDataElseLoad` để trả về dữ liệu đã cache nếu có. Trong trường hợp này, người dùng có thể không nhận được dữ liệu mới nhất tuyệt đối, nhưng thời gian tải sẽ nhanh hơn bất kể kết nối internet có chập chờn đến đâu. Cache được cập nhật thường xuyên, vì vậy hoàn toàn an toàn khi dùng trong phiên làm việc để tránh các yêu cầu mạng. Lưu ý rằng cache vẫn được giữ nguyên khi khởi động lại ứng dụng và chỉ bị xóa khi gỡ cài đặt ứng dụng hoặc thực hiện dọn dẹp thủ công. Adapty SDK lưu trữ onboarding cục bộ theo hai lớp: cache được cập nhật thường xuyên như mô tả ở trên và onboarding dự phòng. Chúng tôi cũng sử dụng CDN để tải onboarding nhanh hơn và một máy chủ dự phòng độc lập phòng khi CDN không thể truy cập. Hệ thống này được thiết kế để đảm bảo bạn luôn nhận được phiên bản onboarding mới nhất trong khi vẫn đảm bảo độ tin cậy ngay cả khi kết nối internet khan hiếm.

locale

tùy chọn

mặc định: en

Mã định danh của bản dịch onboarding. Tham số này cần là mã ngôn ngữ gồm một hoặc hai thẻ con được phân tách bằng ký tự dấu trừ (-). Thẻ con đầu tiên là cho ngôn ngữ, thẻ con thứ hai là cho vùng.
Ví dụ: en là tiếng Anh, pt-br là tiếng Bồ Đào Nha (Brazil).

fetchPolicy

mặc định: .reloadRevalidatingCacheData

Theo mặc định, SDK sẽ cố tải dữ liệu từ máy chủ và trả về dữ liệu đã cache nếu xảy ra lỗi. Chúng tôi khuyên dùng tùy chọn này vì nó đảm bảo người dùng luôn nhận được dữ liệu mới nhất.

Tuy nhiên, nếu bạn cho rằng người dùng thường gặp kết nối internet không ổn định, hãy cân nhắc dùng .returnCacheDataElseLoad để trả về dữ liệu đã cache nếu có. Trong trường hợp này, người dùng có thể không nhận được dữ liệu mới nhất tuyệt đối, nhưng thời gian tải sẽ nhanh hơn bất kể kết nối internet có chập chờn đến đâu. Cache được cập nhật thường xuyên, vì vậy hoàn toàn an toàn khi dùng trong phiên làm việc để tránh các yêu cầu mạng.

Lưu ý rằng cache vẫn được giữ nguyên khi khởi động lại ứng dụng và chỉ bị xóa khi gỡ cài đặt ứng dụng hoặc thực hiện dọn dẹp thủ công.

Adapty SDK lưu trữ onboarding cục bộ theo hai lớp: cache được cập nhật thường xuyên như mô tả ở trên và onboarding dự phòng. Chúng tôi cũng sử dụng CDN để tải onboarding nhanh hơn và một máy chủ dự phòng độc lập phòng khi CDN không thể truy cập. Hệ thống này được thiết kế để đảm bảo bạn luôn nhận được phiên bản onboarding mới nhất trong khi vẫn đảm bảo độ tin cậy ngay cả khi kết nối internet khan hiếm.