Lấy thông tin paywall và sản phẩm cho paywall remote config trong Android SDK

Trước khi hiển thị remote config và các paywall tùy chỉnh, bạn cần lấy thông tin về chúng. Lưu ý rằng chủ đề này đề cập đến remote config và các paywall tùy chỉnh. Để biết hướng dẫn lấy paywall cho các paywall được tùy chỉnh bằng Paywall Builder, vui lòng xem Lấy paywall Paywall Builder và cấu hình của chúng.

Muốn xem ví dụ thực tế về cách tích hợp Adapty SDK vào ứng dụng di động? Hãy xem ứng dụng mẫu của chúng tôi, nơi minh họa toàn bộ quá trình thiết lập, bao gồm hiển thị paywall, thực hiện mua hàng và các chức năng cơ bản khác.

Trước khi bắt đầu lấy paywall và sản phẩm trong ứng dụng (nhấn để mở rộng)

Tạo sản phẩm trong Adapty Dashboard.
Tạo paywall và thêm sản phẩm vào paywall trong Adapty Dashboard.
Tạo placement và thêm paywall vào placement trong Adapty Dashboard.
Cài đặt Adapty SDK trong ứng dụng của bạn.

Lấy thông tin paywall

Trong Adapty, một sản phẩm là sự kết hợp của các sản phẩm từ cả App Store và Google Play. Các sản phẩm đa nền tảng này được tích hợp vào các paywall, cho phép bạn hiển thị chúng tại các placement cụ thể trong ứng dụng.

Để hiển thị các sản phẩm, bạn cần lấy một Paywall từ một trong các placement của mình bằng phương thức getPaywall.

Đừng hardcode ID sản phẩm. ID duy nhất bạn nên hardcode là placement ID. Paywall được cấu hình từ xa, vì vậy số lượng sản phẩm và ưu đãi có thể thay đổi bất kỳ lúc nào. Ứng dụng của bạn phải xử lý các thay đổi này một cách linh động — nếu hôm nay paywall trả về hai sản phẩm và ngày mai trả về ba, hãy hiển thị tất cả mà không cần thay đổi code.

Adapty.getPaywall("YOUR_PLACEMENT_ID", locale = "en") { result ->
    when (result) {
        is AdaptyResult.Success -> {
            val paywall = result.value
            // the requested paywall
        }
        is AdaptyResult.Error -> {
            val error = result.error
            // handle the error
        }
    }
}

Adapty.getPaywall("YOUR_PLACEMENT_ID", "en", result -> {
    if (result instanceof AdaptyResult.Success) {
        AdaptyPaywall paywall = ((AdaptyResult.Success<AdaptyPaywall>) result).getValue();
        // the requested paywall
      
    } else if (result instanceof AdaptyResult.Error) {
        AdaptyError error = ((AdaptyResult.Error) result).getError();
        // handle the error
      
    }
});

Tham số	Bắt buộc	Mô tả
placementId	bắt buộc	Định danh của Placement. Đâ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 paywall. Tham số này được xác định là mã ngôn ngữ gồm một hoặc nhiều thẻ con phân cách bởi dấu trừ (-). Thẻ đầu tiên là ngôn ngữ, thẻ thứ hai là vùng. Ví dụ: `en` là tiếng Anh, `pt-br` là tiếng Bồ Đào Nha Brazil. Xem Bản địa hóa và mã locale để 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 đã lưu trong cache nếu thất bại. Chúng tôi khuyến nghị cách 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 sẽ trải nghiệm thời gian tải nhanh hơn bất kể chất lượng kết nối. Cache được cập nhật thường xuyên, nên an toàn khi dùng trong phiên để tránh các yêu cầu mạng. Lưu ý rằng cache vẫn còn sau khi khởi động lại ứng dụng và chỉ bị xóa khi ứng dụng được cài đặt lại hoặc dọn dẹp thủ công. Adapty SDK lưu trữ paywall theo hai lớp: cache được cập nhật thường xuyên như mô tả ở trên và paywall dự phòng. Chúng tôi cũng dùng CDN để lấy paywall nhanh hơn và một server dự phòng riêng 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 paywall đồng thời đảm bảo độ tin cậy ngay cả khi kết nối internet yếu.
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`, vì thao tác có thể bao gồm nhiều yêu cầu khác nhau bên dưới.

Đừng hardcode ID sản phẩm! Vì paywall được cấu hình từ xa, các sản phẩm khả dụng, số lượng sản phẩm và ưu đãi đặc biệt (như dùng thử miễn phí) có thể thay đổi theo thời gian. Hãy đảm bảo code của bạn xử lý được các tình huống này.
Ví dụ, nếu ban đầu bạn lấy được 2 sản phẩm, ứng dụng nên hiển thị 2 sản phẩm đó. Tuy nhiên, nếu sau này bạn lấy được 3 sản phẩm, ứng dụng nên hiển thị cả 3 mà không cần thay đổi code. Thứ duy nhất bạn phải hardcode là placement ID.

Tham số phản hồi:

Tham số	Mô tả
Paywall	Đối tượng `AdaptyPaywall` với: danh sách ID sản phẩm, định danh paywall, Remote Config và một số thuộc tính khác.

Lấy sản phẩm

Sau khi có paywall, bạn có thể truy vấn mảng sản phẩm tương ứng với nó:

Adapty.getPaywallProducts(paywall) { result ->
    when (result) {
        is AdaptyResult.Success -> {
            val products = result.value
            // the requested products
        }
        is AdaptyResult.Error -> {
            val error = result.error
            // handle the error
        }
    }
}

Adapty.getPaywallProducts(paywall, result -> {
    if (result instanceof AdaptyResult.Success) {
        List<AdaptyPaywallProduct> products = ((AdaptyResult.Success<List<AdaptyPaywallProduct>>) result).getValue();
        // the requested products
      
    } else if (result instanceof AdaptyResult.Error) {
        AdaptyError error = ((AdaptyResult.Error) result).getError();
        // handle the error
      
    }
});

Tham số phản hồi:

Tham số	Mô tả
Products	Danh sách các đối tượng `AdaptyPaywallProduct` với: định danh sản phẩm, tên sản phẩm, giá, tiền tệ, thời hạn gói đăng ký và một số thuộc tính khác.

Khi tự xây dựng giao diện paywall, bạn có thể cần truy cập các thuộc tính từ đối tượng AdaptyPaywallProduct. Dưới đây là các thuộc tính được dùng phổ biến nhất, nhưng hãy tham khảo tài liệu được liên kết để xem đầy đủ tất cả các thuộc tính.

Thuộc tính	Mô tả
Title	Để hiển thị tiêu đề sản phẩm, dùng `product.localizedTitle`. Lưu ý rằng bản địa hóa dựa trên quốc gia cửa hàng mà người dùng đã chọn, không phải locale của thiết bị.
Price	Để hiển thị phiên bản đã được bản địa hóa của giá, dùng `product.price.localizedString`. Bản địa hóa này dựa trên thông tin locale của thiết bị. Bạn cũng có thể truy cập giá dưới dạng số bằng `product.price.amount`. Giá trị sẽ được cung cấp theo đơn vị tiền tệ địa phương. Để lấy ký hiệu tiền tệ tương ứng, dùng `product.price.currencySymbol`.
Subscription Period	Để hiển thị chu kỳ (ví dụ: tuần, tháng, năm, v.v.), dùng `product.subscriptionDetails?.localizedSubscriptionPeriod`. Bản địa hóa này dựa trên locale của thiết bị. Để lấy chu kỳ gói đăng ký theo kiểu lập trình, dùng `product.subscriptionDetails?.subscriptionPeriod`. Từ đó bạn có thể truy cập enum `unit` để lấy độ dài (tức là DAY, WEEK, MONTH, YEAR, hoặc UNKNOWN). Giá trị `numberOfUnits` sẽ cho bạn biết số đơn vị chu kỳ. Ví dụ, với gói đăng ký hàng quý, bạn sẽ thấy `MONTH` trong thuộc tính unit và `3` trong thuộc tính numberOfUnits.
Introductory Offer	Để hiển thị huy hiệu hoặc chỉ báo cho thấy gói đăng ký có ưu đãi giới thiệu, hãy xem thuộc tính `product.subscriptionDetails?.introductoryOfferPhases`. Đây là danh sách có thể chứa tối đa hai giai đoạn giảm giá: giai đoạn dùng thử miễn phí và giai đoạn giá ưu đãi giới thiệu. Trong mỗi đối tượng giai đoạn có các thuộc tính hữu ích sau: • `paymentMode`: enum với các giá trị `FREE_TRIAL`, `PAY_AS_YOU_GO`, `PAY_UPFRONT` và `UNKNOWN`. Dùng thử miễn phí sẽ có kiểu `FREE_TRIAL`. • `price`: Giá giảm dưới dạng số. Với dùng thử miễn phí, hãy tìm `0` ở đây. • `localizedNumberOfPeriods`: chuỗi được bản địa hóa theo locale của thiết bị mô tả độ dài ưu đãi. Ví dụ, ưu đãi dùng thử ba ngày hiển thị `3 days` trong trường này. • `subscriptionPeriod`: Ngoài ra, bạn có thể lấy chi tiết riêng lẻ của chu kỳ ưu đãi với thuộc tính này. Nó hoạt động tương tự cho ưu đãi như phần trước đã mô tả. • `localizedSubscriptionPeriod`: Chu kỳ gói đăng ký đã được định dạng theo locale của người dùng.

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

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

Để giải quyết điều này, bạn có thể dùng phương thức getPaywallForDefaultAudience, phương thức này lấy paywall 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 paywall bằng phương thức getPaywall, như đã trình bày chi tiết trong phần Lấy thông tin paywall ở trên.

Tại sao chúng tôi khuyến nghị dùng getPaywall

Phương thức getPaywallForDefaultAudience có một vài nhược điểm đáng kể:

Vấn đề tương thích ngược tiềm ẩn: Nếu bạn cần hiển thị các paywall khác nhau cho các phiên bản ứng dụng khác nhau (hiện tại và tương lai), bạn có thể gặp khó khăn. Bạn sẽ phải thiết kế các paywall hỗ trợ phiên bản hiện tại (cũ) hoặc chấp nhận rằng người dùng với phiên bản hiện tại (cũ) có thể gặp sự cố với paywall không hiển thị được.
Mất khả năng nhắm mục tiêu: Tất cả người dùng sẽ thấy cùng một paywall được thiết kế cho đối tượng All Users, nghĩa là bạn mất khả năng nhắm mục tiêu cá nhân hóa (bao gồm theo quốc gia, attribution marketing hoặc các thuộc tính tùy chỉnh của bạn).

Nếu bạn sẵn sàng chấp nhận những nhược điểm này để có lợi ích từ việc lấy paywall nhanh hơn, hãy dùng phương thức getPaywallForDefaultAudience như sau. Nếu không, hãy tiếp tục dùng getPaywall được mô tả ở trên.

Adapty.getPaywallForDefaultAudience("YOUR_PLACEMENT_ID", locale = "en") { result ->
    when (result) {
        is AdaptyResult.Success -> {
            val paywall = result.value
            // the requested paywall
        }
        is AdaptyResult.Error -> {
            val error = result.error
            // handle the error
        }
    }
}

Adapty.getPaywallForDefaultAudience("YOUR_PLACEMENT_ID", "en", result -> {
    if (result instanceof AdaptyResult.Success) {
        AdaptyPaywall paywall = ((AdaptyResult.Success<AdaptyPaywall>) result).getValue();
        // the requested paywall
      
    } else if (result instanceof AdaptyResult.Error) {
        AdaptyError error = ((AdaptyResult.Error) result).getError();
        // handle the error
      
    }
});

Phương thức getPaywallForDefaultAudience khả dụng từ Android SDK phiên bản 2.11.3 trở lên.

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

placementId bắt buộc Định danh của Placement. Đâ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 paywall. Tham số này được xác định là mã ngôn ngữ gồm một hoặc nhiều thẻ con phân cách bởi dấu trừ (-). Thẻ đầu tiên là ngôn ngữ, thẻ thứ hai là vùng.

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

Xem Bản địa hóa và mã locale để 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 đã lưu trong cache nếu thất bại. Chúng tôi khuyến nghị cách 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 sẽ trải nghiệm thời gian tải nhanh hơn bất kể chất lượng kết nối. Cache được cập nhật thường xuyên, nên an toàn khi dùng trong phiên để tránh các yêu cầu mạng.

Lưu ý rằng cache vẫn còn sau khi khởi động lại ứng dụng và chỉ bị xóa khi ứng dụng được cài đặt lại hoặc dọn dẹp thủ công.