Lấy paywalls và sản phẩm cho remote config paywalls trong Unity SDK

Trước khi hiển thị Remote Config và 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à paywall tùy chỉnh. Để biết hướng dẫn lấy flow hoặc paywall được tùy chỉnh trong Flow & Paywall Builder hoặc old Paywall Builder, vui lòng tham khảo Lấy flow & paywall.

Tip

Bạn 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, 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 tải flow và sản phẩm trong ứng dụng di động của bạn (nhấn để mở rộng)

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

Lấy thông tin flow

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 flow và paywall, cho phép bạn hiển thị chúng trong các placement cụ thể của ứng dụng di động.

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

Important

Đừng hardcode product ID. ID duy nhất bạn nên hardcode là placement ID. Các flow được cấu hình từ xa, nên số lượng sản phẩm và ưu đãi có thể thay đổi bất cứ lúc nào. Ứng dụng của bạn phải xử lý những thay đổi này một cách linh hoạt—nếu hôm nay một flow 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.GetFlow(
    "YOUR_PLACEMENT_ID",
    AdaptyPlacementFetchPolicy.Default,
    TimeSpan.FromSeconds(5),
    (flow, error) => {
        if (error != null) {
            // handle the error
            return;
        }

        // flow - the requested flow
    }
);

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

placementId bắt buộc Mã định danh của Placement. Đâ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. Đây là giá trị bạn đã chỉ định khi tạo placement trong Adapty Dashboard.
fetchPolicy	mặc định: `AdaptyPlacementFetchPolicy.Default`	`fetchPolicy` xác định SDK đọc từ lớp nào trước, chứ không phải việc có được phép dùng cache hay không. Mặc định, SDK sẽ gọi lên server trước và chỉ trả về dữ liệu đã cache nếu yêu cầu đó thất bại. Chúng tôi khuyến nghị 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 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 `AdaptyPlacementFetchPolicy.ReturnCacheDataElseLoad` — tùy chọn này đảo ngược thứ tự ưu tiên: đọc cache trước, chỉ gọi server khi không có gì trong cache. 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 mạng có chập chờn thế nào. Cache được cập nhật thường xuyên nên hoàn toàn an toàn khi dùng trong phiên để tránh các request mạng không cần thiết. Chính sách thứ ba, `AdaptyPlacementFetchPolicy.ReturnCacheDataIfNotExpiredElseLoad(maxAge)`, nằm giữa hai tùy chọn trên: đọc cache trước nếu bản cache còn trẻ hơn `TimeSpan` bạn truyền vào, và gọi server khi bản cache đã cũ hơn giá trị đó. Lưu ý rằng cache vẫn còn nguyên sau 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ữ flow và paywall ở 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 để tải flow và paywall nhanh hơn, cùng một server dự phòng độc lập đề phòng CDN không khả dụng. 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 flow và paywall, đồng thời vẫn đảm bảo độ tin cậy ngay cả khi kết nối mạng hạn chế.
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ể timeout muộn hơn một chút so với giá trị đã chỉ định trong `loadTimeout`, do bên dưới thao tác có thể bao gồm nhiều request khác nhau.

fetchPolicy

mặc định: AdaptyPlacementFetchPolicy.Default

fetchPolicy xác định SDK đọc từ lớp nào trước, chứ không phải việc có được phép dùng cache hay không. Mặc định, SDK sẽ gọi lên server trước và chỉ trả về dữ liệu đã cache nếu yêu cầu đó thất bại. Chúng tôi khuyến nghị 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 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 AdaptyPlacementFetchPolicy.ReturnCacheDataElseLoad — tùy chọn này đảo ngược thứ tự ưu tiên: đọc cache trước, chỉ gọi server khi không có gì trong cache. 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 mạng có chập chờn thế nào. Cache được cập nhật thường xuyên nên hoàn toàn an toàn khi dùng trong phiên để tránh các request mạng không cần thiết.

Chính sách thứ ba, AdaptyPlacementFetchPolicy.ReturnCacheDataIfNotExpiredElseLoad(maxAge), nằm giữa hai tùy chọn trên: đọc cache trước nếu bản cache còn trẻ hơn TimeSpan bạn truyền vào, và gọi server khi bản cache đã cũ hơn giá trị đó.

Lưu ý rằng cache vẫn còn nguyên sau 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ữ flow và paywall ở 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 để tải flow và paywall nhanh hơn, cùng một server dự phòng độc lập đề phòng CDN không khả dụng. 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 flow và paywall, đồng thời vẫn đảm bảo độ tin cậy ngay cả khi kết nối mạng hạn chế.

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ể timeout muộn hơn một chút so với giá trị đã chỉ định trong loadTimeout, do bên dưới thao tác có thể bao gồm nhiều request khác nhau.

Đừng hardcode product ID! Vì các flow được cấu hình từ xa, các sản phẩm hiện có, số lượng sản phẩm và các ưu đãi đặc biệt (chẳng hạn 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 trường hợp 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ố trả về:

Tham số	Mô tả
Flow	Một đối tượng `AdaptyFlow` bao gồm: mã định danh flow, các biến thể paywall (`Paywalls` — mỗi biến thể có danh sách mã sản phẩm riêng), danh sách `RemoteConfigs` (một mục cho mỗi locale đã cấu hình), và một số thuộc tính khác. Để lấy sản phẩm cho flow, hãy gọi `GetPaywallProducts(flow)`.

Note

Trong v4, GetFlow không có tham số locale. Khi bạn render một flow bằng CreateFlowView, ngôn ngữ sẽ được tự động xác định. Đối với các paywall tùy chỉnh, tất cả các ngôn ngữ hiện có được trả về cùng nhau trong flow.RemoteConfigs — hãy chọn ngôn ngữ phù hợp với thiết bị của người dùng hoặc cài đặt trong ứng dụng của bạn. Xem Bản địa hóa và mã ngôn ngữ để biết thêm chi tiết.

Lấy danh sách sản phẩm

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

Adapty.GetPaywallProducts(flow, (products, error) => {
    if (error != null) {
        // handle the error
        return;
    }

    // products - the requested products array
});

Tham số phản hồi:

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

Khi triển khai thiết kế flow của riêng bạn, bạn sẽ 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 sử dụng phổ biến nhất.

Thuộc tính	Mô tả
Title	Để hiển thị tiêu đề sản phẩm, sử dụng `product.LocalizedTitle`. Lưu ý rằng nội dung 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 ngôn ngữ của thiết bị.
Price	Để hiển thị giá đã được bản địa hóa, sử dụng `product.Price.LocalizedString`. Nội dung 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ố thông qua `product.Price.Amount`. Giá trị sẽ được tính theo đơn vị tiền tệ địa phương. Để lấy ký hiệu tiền tệ tương ứng, sử dụng `product.Price.CurrencySymbol`.
Subscription Period	Để hiển thị chu kỳ (ví dụ: tuần, tháng, năm, v.v.), sử dụng `product.Subscription?.LocalizedPeriod`. Nội dung 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 cách lập trình, sử dụng `product.Subscription?.Period`. Từ đó bạn có thể truy cập enum `Unit` để biết độ dài (ví dụ: `AdaptySubscriptionPeriodUnit.Day`, `AdaptySubscriptionPeriodUnit.Week`, `AdaptySubscriptionPeriodUnit.Month`, `AdaptySubscriptionPeriodUnit.Year`, hoặc `AdaptySubscriptionPeriodUnit.Unknown`). Giá trị `NumberOfUnits` cho biết số đơn vị chu kỳ. Ví dụ: với gói đăng ký theo quý, bạn sẽ thấy `AdaptySubscriptionPeriodUnit.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 biết gói đăng ký có ưu đãi giới thiệu, hãy kiểm tra thuộc tính `product.Subscription?.Offer?.Phases`. Đâ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á 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`: một enum với các giá trị `AdaptyPaymentMode.FreeTrial`, `AdaptyPaymentMode.PayAsYouGo`, `AdaptyPaymentMode.PayUpFront`, và `AdaptyPaymentMode.Unknown`. Dùng thử miễn phí sẽ là loại `AdaptyPaymentMode.FreeTrial`. • `Price`: Một đối tượng `AdaptyPrice` với giá đã giảm — sử dụng `Price.Amount` để lấy số và `Price.LocalizedString` để hiển thị. Với dùng thử miễn phí, hãy tìm giá trị `0` trong `Price.Amount`. • `LocalizedNumberOfPeriods`: một chuỗi được bản địa hóa theo locale của thiết bị, mô tả thời gian của ưu đãi. Ví dụ: ưu đãi dùng thử ba ngày sẽ hiển thị `"3 days"` trong trường này. • `SubscriptionPeriod`: Ngoài ra, bạn có thể lấy thông tin chi tiết về chu kỳ ưu đãi thông qua thuộc tính này. Cách hoạt động với ưu đãi tương tự như mô tả ở phần trước. • `LocalizedSubscriptionPeriod`: Chu kỳ gói đăng ký được định dạng theo locale của người dùng cho giai đoạn giảm giá.

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

Thông thường, flow đượ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ối ưu quá trình này. Tuy nhiên, trong trường hợp bạn có nhiều đối tượng và placement, và người dùng của bạn có kết nối internet yếu, việc tải flow có thể mất nhiều thời gian hơn mong muốn. Trong tình huống như vậy, bạn có thể muốn hiển thị một flow mặc định để đảm bảo trải nghiệm người dùng mượt mà thay vì không hiển thị gì cả.

Để giải quyết vấn đề này, bạn có thể sử dụng phương thức GetFlowForDefaultAudience, phương thức này sẽ lấy flow 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à lấy flow bằng phương thức GetFlow, như được mô tả chi tiết trong phần Lấy thông tin flow ở trên.

Warning

Lý do chúng tôi khuyến nghị sử dụng GetFlow

Phương thức GetFlowForDefaultAudience có một số hạn chế đáng kể:

Vấn đề tương thích ngược tiềm ẩn: Nếu bạn cần hiển thị các flow 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 flow 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 các flow 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 flow được thiết kế cho đối tượng All Users, nghĩa là bạn mất đi khả năng cá nhân hóa nhắm mục tiêu (bao gồm dựa trên quốc gia, attribution marketing hoặc các thuộc tính tùy chỉnh của riêng bạn).

Nếu bạn sẵn sàng chấp nhận những hạn chế này để đổi lấy tốc độ tải flow nhanh hơn, hãy sử dụng phương thức GetFlowForDefaultAudience như sau. Nếu không, hãy tiếp tục dùng GetFlow đã được mô tả ở trên.

Adapty.GetFlowForDefaultAudience(
    "YOUR_PLACEMENT_ID",
    AdaptyPlacementFetchPolicy.Default,
    (flow, error) => {
        if (error != null) {
            // handle the error
            return;
        }

        // flow - the requested flow
    }
);

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

placementId bắt buộc Mã định danh của Placement. Đâ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. Đây là giá trị bạn đã chỉ định khi tạo placement trong Adapty Dashboard.
fetchPolicy	mặc định: `AdaptyPlacementFetchPolicy.Default`	`fetchPolicy` xác định lớp nào SDK đọc trước, chứ không phải liệu nó có thể sử dụng cache hay không. Theo mặc định, SDK sẽ gọi lên server trước và trả về dữ liệu từ cache nếu yêu cầu đó 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 thường xuyên gặp kết nối internet không ổn định, hãy cân nhắc dùng `AdaptyPlacementFetchPolicy.ReturnCacheDataElseLoad` — chính sách này đảo ngược thứ tự đó: đọc cache trước và chỉ gọi lên server khi không có gì trong cache. 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ó trải nghiệm tải nhanh hơn, bất kể kết nối internet của họ có chập chờn thế nào. Cache được cập nhật thường xuyên, nên hoàn toàn an toàn khi dùng trong phiên để tránh các yêu cầu mạng. Chính sách thứ ba, `AdaptyPlacementFetchPolicy.ReturnCacheDataIfNotExpiredElseLoad(maxAge)`, nằm giữa hai chính sách trên: nó đọc cache trước khi bản sao được lưu trong cache còn trẻ hơn `TimeSpan` bạn truyền vào, và gọi lên server khi đã cũ hơn. Lưu ý rằng cache vẫn còn nguyên sau 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.

fetchPolicy

mặc định: AdaptyPlacementFetchPolicy.Default

fetchPolicy xác định lớp nào SDK đọc trước, chứ không phải liệu nó có thể sử dụng cache hay không. Theo mặc định, SDK sẽ gọi lên server trước và trả về dữ liệu từ cache nếu yêu cầu đó 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 thường xuyên gặp kết nối internet không ổn định, hãy cân nhắc dùng AdaptyPlacementFetchPolicy.ReturnCacheDataElseLoad — chính sách này đảo ngược thứ tự đó: đọc cache trước và chỉ gọi lên server khi không có gì trong cache. 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ó trải nghiệm tải nhanh hơn, bất kể kết nối internet của họ có chập chờn thế nào. Cache được cập nhật thường xuyên, nên hoàn toàn an toàn khi dùng trong phiên để tránh các yêu cầu mạng.

Chính sách thứ ba, AdaptyPlacementFetchPolicy.ReturnCacheDataIfNotExpiredElseLoad(maxAge), nằm giữa hai chính sách trên: nó đọc cache trước khi bản sao được lưu trong cache còn trẻ hơn TimeSpan bạn truyền vào, và gọi lên server khi đã cũ hơn.

Lưu ý rằng cache vẫn còn nguyên sau 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.

Trước khi hiển thị Remote Config và paywall tùy chỉnh, bạn cần lấy thông tin về chúng. Lưu ý rằng phần này đề cập đến Remote Config và 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 tham khảo Lấy paywall Paywall Builder và cấu hình của chúng.

Tip

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

Tạo sản phẩm của bạn trong Adapty Dashboard.
Tạo paywall và thêm sản phẩm vào paywall của bạn trên Adapty Dashboard.
Tạo placement và thêm paywall vào placement trên Adapty Dashboard.
Cài đặt Adapty SDK trong ứng dụng di độ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 mobile.

Để 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.

Important

Đừng hardcode ID sản phẩm. ID duy nhất bạn nên hardcode là placement ID. Các paywall được cấu hình từ xa, vì vậy số lượng sản phẩm và ưu đãi hiện có có thể thay đổi bất cứ 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 hoạt—nếu hôm nay một paywall trả về hai sản phẩm và ngày mai trả về ba sản phẩm, hãy hiển thị tất cả chúng mà không cần thay đổi code.

Adapty.GetPaywall("YOUR_PLACEMENT_ID", "en", (paywall, error) => {
  if(error != null) {
    // handle the error
    return;
  }
  
  // paywall - the resulting object
});

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 một 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 là mã ngôn ngữ gồm một hoặc nhiều thẻ con được phân tách bằng ký tự dấu trừ (-). Thẻ con đầu tiên là ngôn ngữ, thẻ con thứ hai là khu vực. 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 chúng.
fetchPolicy	mặc định: `AdaptyPlacementFetchPolicy.Default`	`fetchPolicy` xác định lớp nào SDK đọc trước, không phải việc có thể dùng cache hay không. Theo mặc định, SDK sẽ gọi lên server trước và trả về dữ liệu đã cache nếu yêu cầu đó 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 thường xuyên gặp tình trạng kết nối internet không ổn định, hãy cân nhắc `AdaptyPlacementFetchPolicy.ReturnCacheDataElseLoad` — tùy chọn này đảo ngược thứ tự đó: đọc cache trước và chỉ gọi server khi chưa có gì trong cache. Người dùng có thể không nhận được dữ liệu mới nhất tuyệt đối, nhưng sẽ tải nhanh hơn bất kể kết nối internet có bấp bênh đến đâu. 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. Chính sách thứ ba, `AdaptyPlacementFetchPolicy.ReturnCacheDataIfNotExpiredElseLoad(maxAge)`, nằm giữa hai tùy chọn trên: đọc cache trước khi bản cache còn trẻ hơn `TimeSpan` bạn truyền vào, và gọi server khi cache đã cũ hơn giá trị đó. Lưu ý rằng cache vẫn được giữ nguyên sau 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ữ paywall ở 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 sử dụng CDN để tải paywall 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 mới nhất của paywall, đồng thời đảm bảo độ tin cậy ngay cả khi kết nối internet 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ể vượt quá thời gian chờ đã chỉ định trong `loadTimeout` một chút, do 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ì các paywall được cấu hình từ xa, các sản phẩm có sẵn, số lượng sản phẩm và các ư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 của bạn 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 của bạn nên hiển thị cả 3 sản phẩm 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	Một đối tượng `AdaptyPaywall` gồm: 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, (products, error) => {
  if(error != null) {
    // handle the error
    return;
  }
  
  // products - the requested products array
});

Tham số phản hồi:

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

Khi triển khai thiết kế paywall của riêng bạn, bạn có thể cần truy cập các thuộc tính này từ đối tượng AdaptyPaywallProduct. Dưới đây là các thuộc tính được sử dụng phổ biến nhất, nhưng hãy tham khảo tài liệu được liên kết để biết đầy đủ chi tiết về tất cả các thuộc tính có sẵn.

Thuộc tính	Mô tả
Title	Để hiển thị tiêu đề sản phẩm, sử dụng `product.LocalizedTitle`. Lưu ý rằng việc bản địa hóa dựa trên quốc gia cửa hàng mà người dùng đã chọn, chứ không phải ngôn ngữ của thiết bị.
Price	Để hiển thị giá đã được bản địa hóa, sử dụng `product.Price.LocalizedString`. Việc bản địa hóa này dựa trên thông tin ngôn ngữ của thiết bị. Bạn cũng có thể lấy giá dưới dạng số bằng `product.Price.Amount`. Giá trị sẽ được trả về theo đơn vị tiền tệ địa phương. Để lấy ký hiệu tiền tệ tương ứng, sử dụng `product.Price.CurrencySymbol`.
Subscription Period	Để hiển thị chu kỳ (ví dụ: tuần, tháng, năm, v.v.), sử dụng `product.Subscription?.LocalizedPeriod`. Việc bản địa hóa này dựa trên ngôn ngữ của thiết bị. Để lấy chu kỳ gói đăng ký theo cách lập trình, sử dụng `product.Subscription?.Period`. Từ đó bạn có thể truy cập enum `Unit` để lấy độ dài (tức là `AdaptySubscriptionPeriodUnit.Day`, `AdaptySubscriptionPeriodUnit.Week`, `AdaptySubscriptionPeriodUnit.Month`, `AdaptySubscriptionPeriodUnit.Year`, hoặc `AdaptySubscriptionPeriodUnit.Unknown`). Giá trị `NumberOfUnits` sẽ cho bạn biết số đơn vị chu kỳ. Ví dụ, đối với gói đăng ký theo quý, bạn sẽ thấy `AdaptySubscriptionPeriodUnit.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 khác cho biết gói đăng ký có ưu đãi giới thiệu, hãy kiểm tra thuộc tính `product.Subscription?.Offer?.Phases`. Đây là một 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á 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`: một enum với các giá trị `AdaptyPaymentMode.FreeTrial`, `AdaptyPaymentMode.PayAsYouGo`, `AdaptyPaymentMode.PayUpFront`, và `AdaptyPaymentMode.Unknown`. Dùng thử miễn phí sẽ thuộc loại `AdaptyPaymentMode.FreeTrial`. • `Price`: Một đối tượng `AdaptyPrice` với giá đã giảm — sử dụng `Price.Amount` để lấy số và `Price.LocalizedString` để hiển thị. Với dùng thử miễn phí, hãy tìm giá trị `0` trong `Price.Amount`. • `LocalizedNumberOfPeriods`: một chuỗi được bản địa hóa theo ngôn ngữ thiết bị, mô tả độ dài của ưu đãi. Ví dụ, ưu đãi dùng thử ba ngày sẽ hiển thị `"3 days"` trong trường này. • `SubscriptionPeriod`: Ngoài ra, bạn có thể lấy thông tin chi tiết về chu kỳ ưu đãi bằng thuộc tính này. Cách hoạt động tương tự như đã mô tả ở phần trước. • `LocalizedSubscriptionPeriod`: Chu kỳ gói đăng ký của ưu đãi được định dạng theo ngôn ngữ 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, các 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 những trường hợp bạn có nhiều đối tượng và paywall, và người dùng của bạn 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 cả.

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

Warning

Hãy cân nhắc sử dụng GetPaywall thay vì GetPaywallForDefaultAudience, 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 phả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”, không hỗ trợ nhắm mục tiêu theo quốc gia, attribution, hay thuộc tính tùy chỉnh.

Nếu tốc độ tải nhanh hơn quan trọng hơn những hạn chế này với trường hợp của bạn, hãy dùng GetPaywallForDefaultAudience như hướng dẫn bên dưới. Ngược lại, hãy dùng GetPaywall như đã mô tả ở trên.

Adapty.GetPaywallForDefaultAudience("YOUR_PLACEMENT_ID", "en", (paywall, error) => {
  if(error != null) {
    // handle the error
    return;
  }
  
  // paywall - the resulting object
});

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.

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 paywall. Tham số này được kỳ vọng là một 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 khu vực. 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: `AdaptyPlacementFetchPolicy.Default`	`fetchPolicy` xác định SDK đọc lớp nào trước, chứ không phải liệu nó có thể sử dụng cache hay không. Theo mặc định, SDK sẽ truy cập server trước và trả về dữ liệu đã cache nếu yêu cầu đó 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 của bạn 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 phải kết nối internet không ổn định, hãy cân nhắc `AdaptyPlacementFetchPolicy.ReturnCacheDataElseLoad`, tùy chọn này đảo ngược thứ tự đó — đọc cache trước và chỉ truy cập server khi không có gì trong cache. 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ó trải nghiệm tải nhanh hơn, bất kể kết nối internet của họ có chập chờn thế nào. Cache được cập nhật thường xuyên, vì vậy việc sử dụng nó trong phiên để tránh các yêu cầu mạng là an toàn. Chính sách thứ ba, `AdaptyPlacementFetchPolicy.ReturnCacheDataIfNotExpiredElseLoad(maxAge)`, nằm giữa hai chính sách trên: nó đọc cache trước khi bản cache còn trẻ hơn `TimeSpan` bạn truyền vào, và truy cập server khi bản cache đó cũ hơn. Lưu ý rằng cache vẫn còn nguyê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 thông qua quá trình dọn dẹp thủ công. Adapty SDK lưu trữ paywall cục bộ trong 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 sử dụng CDN để tải paywall nhanh hơn và một server dự phòng độc lập trong trường hợp CDN không thể 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 mới nhất của paywall trong khi vẫn đảm bảo độ tin cậy ngay cả trong trường hợp kết nối internet hạn chế.

locale

tùy chọn

mặc định: en

Định danh của bản địa hóa paywall. Tham số này được kỳ vọng là một 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 khu vực.

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: AdaptyPlacementFetchPolicy.Default

fetchPolicy xác định SDK đọc lớp nào trước, chứ không phải liệu nó có thể sử dụng cache hay không. Theo mặc định, SDK sẽ truy cập server trước và trả về dữ liệu đã cache nếu yêu cầu đó 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 của bạn 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 phải kết nối internet không ổn định, hãy cân nhắc AdaptyPlacementFetchPolicy.ReturnCacheDataElseLoad, tùy chọn này đảo ngược thứ tự đó — đọc cache trước và chỉ truy cập server khi không có gì trong cache. 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ó trải nghiệm tải nhanh hơn, bất kể kết nối internet của họ có chập chờn thế nào. Cache được cập nhật thường xuyên, vì vậy việc sử dụng nó trong phiên để tránh các yêu cầu mạng là an toàn.

Chính sách thứ ba, AdaptyPlacementFetchPolicy.ReturnCacheDataIfNotExpiredElseLoad(maxAge), nằm giữa hai chính sách trên: nó đọc cache trước khi bản cache còn trẻ hơn TimeSpan bạn truyền vào, và truy cập server khi bản cache đó cũ hơn.

Lưu ý rằng cache vẫn còn nguyê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 thông qua quá trình dọn dẹp thủ công.

Adapty SDK lưu trữ paywall cục bộ trong 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 sử dụng CDN để tải paywall nhanh hơn và một server dự phòng độc lập trong trường hợp CDN không thể 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 mới nhất của paywall trong khi vẫn đảm bảo độ tin cậy ngay cả trong trường hợp kết nối internet hạn chế.