Lấy onboarding trong React Native SDK

Sau khi bạn thiết kế phần giao diện cho onboarding bằng builder trong Adapty Dashboard, bạn có thể hiển thị nó trong ứng dụng React Native của mình. Bước đầu tiên trong quá trình này là lấy onboarding gắn 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 React Native SDK phiên bản 3.8.0 trở lên.
Bạn đã tạo một onboarding.
Bạn đã thêm onboarding vào một placement.

Lấy onboarding

Khi bạn tạo một onboarding bằng builder không cần 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ủa bạn cần lấy và hiển thị. Container này quản lý toàn bộ trải nghiệm — nội dung nào xuất hiện, 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 hay dữ liệu nhập vào form). 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 view riêng.

Để có hiệu suất tốt nhất, hãy lấy cấu hình onboarding sớm để hình ả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, sử dụng phương thức getOnboarding:

try {
    const placementId = 'YOUR_PLACEMENT_ID';
    const locale = 'en';

    const onboarding = await adapty.getOnboarding(placementId, locale);
    // the requested onboarding
} catch (error) {
    // handle the error
}

Sau đó, gọi phương thức createOnboardingView để tạo một instance view.

Kết quả của phương thức createOnboardingView chỉ có thể được sử dụng một lần. Nếu bạn cần sử dụng lại, hãy gọi lại phương thức createOnboardingView. Gọi nó hai lần mà không tạo lại có thể dẫn đến lỗi AdaptyUIError.viewAlreadyPresented.

// for the Adapty SDK < 3.14 – import {createOnboardingView} from 'react-native-adapty/dist/ui';

if (onboarding.hasViewConfiguration) {
    try {
        const view = await createOnboardingView(onboarding);
    } catch (error) {
        // handle the error
    }
} else {
    //use your custom logic
}

Các 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 dịch onboarding. Tham số này phải là mã ngôn ngữ gồm một hoặc hai subtag phân cách bằng dấu trừ (-). Subtag đầu tiên là ngôn ngữ, subtag thứ hai là vùng. Ví dụ: `en` là tiếng Anh, `pt-br` là tiếng Bồ Đào Nha (Brazil). Xem Localizations and locale codes để biết thêm thông tin về mã locale và cách chúng tôi khuyến nghị sử dụng.
fetchPolicy	mặc định: `.reloadRevalidatingCacheData`	Theo mặc định, SDK sẽ cố tải dữ liệu từ server và trả về dữ liệu được cache trong trường hợp thất bạ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 có 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 họ sẽ có thời gian tải nhanh hơn dù kết nối mạng không ổn định. Cache được cập nhật thường xuyên, vì vậy có thể dùng nó trong phiên để tránh các request mạng. Lưu ý rằng cache vẫn tồn tại 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ông qua việc dọn dẹp thủ công. Adapty SDK lưu trữ onboarding cục bộ trong 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 server dự phòng độc lập trong trường hợp CDN không truy cập được. 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 hạn chế.
loadTimeoutMs	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ị được chỉ định trong `loadTimeout`, do thao tác có thể bao gồm nhiều request khác nhau bên dưới.

Các tham số trả về:

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

Tăng tốc lấy onboarding với onboarding đối tượng mặc định

Thông thường, onboarding được lấy gần như ngay lập tức, vì vậy 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 những trường hợp bạn có nhiều đối tượng và onboarding, và người dùng có kết nối internet yếu, việc lấy onboarding có thể mất nhiều thời gian hơn bạn muốn. Trong những tình huống đó, 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.

Để 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 lấy onboarding của placement đã 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à lấy onboarding bằng phương thức getOnboarding, như đã mô tả trong phần Lấy onboarding ở trên.

Hãy cân nhắc 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 ứng dụng, đò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ũ hơn có thể hiển thị không chính xác.
Không cá nhân hóa: Chỉ hiển thị nội dung cho đối tượng “All Users”, bỏ qua việc 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 độ lấy nhanh hơn vượt trội hơn những hạn chế này cho trường hợp sử dụng của bạn, hãy dùng getOnboardingForDefaultAudience như bên dưới. Nếu không, hãy dùng getOnboarding như đã mô tả ở trên.

try {
    const placementId = 'YOUR_PLACEMENT_ID';
    const locale = 'en';

    const onboarding = await adapty.getOnboardingForDefaultAudience(placementId, locale);
    // the requested onboarding
} catch (error) {
    // handle the error
}

Các 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 dịch onboarding. Tham số này phải là mã ngôn ngữ gồm một hoặc hai subtag phân cách bằng dấu trừ (-). Subtag đầu tiên là ngôn ngữ, subtag thứ hai là vùng.

Ví dụ: en là tiếng Anh, pt-br là tiếng Bồ Đào Nha (Brazil).

Xem Localizations and locale codes để biết thêm thông tin về mã locale và cách chúng tôi khuyến nghị sử dụng.

fetchPolicy

mặc định: .reloadRevalidatingCacheData

Theo mặc định, SDK sẽ cố tải dữ liệu từ server và trả về dữ liệu được cache trong trường hợp thất bạ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 có 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 họ sẽ có thời gian tải nhanh hơn dù kết nối mạng không ổn định. Cache được cập nhật thường xuyên, vì vậy có thể dùng nó trong phiên để tránh các request mạng.

Lưu ý rằng cache vẫn tồn tại 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ông qua việc dọn dẹp thủ công.

Adapty SDK lưu trữ onboarding cục bộ trong 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 server dự phòng độc lập trong trường hợp CDN không truy cập được. 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 hạn chế.