Hướng dẫn này cung cấp cho nhà phát triển thông tin về cách chia sẻ dữ liệu về gói thuê bao và quyền sử dụng ứng dụng với Google TV bằng Engage SDK. Người dùng có thể tìm thấy nội dung mà họ có quyền sử dụng và cho phép Google TV cung cấp các đề xuất nội dung có mức độ liên quan cao cho người dùng, ngay trong trải nghiệm Google TV trên TV, thiết bị di động và máy tính bảng.
Điều kiện tiên quyết
Bạn phải chuyển đổi nguồn cấp dữ liệu về hành động trên nội dung nghe nhìn trước khi có thể sử dụng API quyền sử dụng thiết bị. Nếu bạn chưa làm việc này, hãy hoàn tất quy trình chuyển đổi nguồn cấp dữ liệu về hành động trên nội dung nghe nhìn media actions feed.
Chuẩn bị trước
Hoàn tất hướng dẫn Chuẩn bị trước trong hướng dẫn Bắt đầu sử dụng.
- Xuất bản thông tin về gói thuê bao trên các sự kiện sau:
- Người dùng đăng nhập vào ứng dụng của bạn.
- Người dùng chuyển đổi giữa các hồ sơ (nếu ứng dụng hỗ trợ hồ sơ).
- Người dùng mua một gói thuê bao mới.
- Người dùng nâng cấp một gói thuê bao hiện có.
- Gói thuê bao của người dùng hết hạn.
Hoạt động tích hợp
Phần này cung cấp các đoạn mã ví dụ và hướng dẫn cần thiết để triển khai SubscriptionEntity nhằm quản lý nhiều loại gói thuê bao.
Gói thuê bao theo hạng phổ biến
Đối với người dùng có gói thuê bao cơ bản cho các dịch vụ của nhà cung cấp nội dung nghe nhìn (ví dụ: một dịch vụ có một hạng gói thuê bao cấp quyền truy cập vào tất cả nội dung có tính phí), hãy cung cấp những thông tin chi tiết cần thiết sau:
SubscriptionType: Cho biết rõ ràng gói thuê bao cụ thể mà người dùng có.SUBSCRIPTION_TYPE_ACTIVE: Người dùng có một gói thuê bao có tính phí đang hoạt động.SUBSCRIPTION_TYPE_ACTIVE_TRIAL: Người dùng có một gói thuê bao dùng thử.SUBSCRIPTION_TYPE_INACTIVE: Người dùng có một tài khoản nhưng không có gói thuê bao hoặc gói dùng thử đang hoạt động.
ExpirationTimeMillis: Thời gian không bắt buộc tính bằng mili giây. Cho biết thời điểm gói thuê bao được đặt để hết hạn.ProviderPackageName: Cho biết tên gói của ứng dụng xử lý gói thuê bao.
Ví dụ về nguồn cấp dữ liệu mẫu của nhà cung cấp nội dung nghe nhìn.
"actionAccessibilityRequirement": [
{
"@type": "ActionAccessSpecification",
"category": "subscription",
"availabilityStarts": "2022-06-01T07:00:00Z",
"availabilityEnds": "2026-05-31T07:00:00Z",
"requiresSubscription": {
"@type": "MediaSubscription",
// Don't match this string,
// ID is only used to for reconciliation purpose
"@id": "https://www.example.com/971bfc78-d13a-4419",
// Don't match this, as name is only used for displaying purpose
"name": "Basic common name",
"commonTier": true
}
Ví dụ sau đây sẽ tạo một SubscriptionEntity cho người dùng:
val subscription = SubscriptionEntity.Builder()
setSubscriptionType(
SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
)
.setProviderPackageName("com.google.android.example")
// Optional
// December 30, 2025 12:00:00AM in milliseconds since epoch
.setExpirationTimeMillis(1767052800000)
.build()
Gói thuê bao Premium
Nếu ứng dụng cung cấp các gói thuê bao trả phí nhiều hạng, bao gồm nội dung hoặc tính năng mở rộng ngoài hạng phổ biến, hãy biểu thị điều này bằng cách thêm một hoặc nhiều quyền sử dụng vào Gói thuê bao.
Quyền sử dụng này có các trường sau:
Identifier: Chuỗi giá trị nhận dạng bắt buộc cho quyền sử dụng này. Giá trị này phải khớp với một trong các giá trị nhận dạng quyền sử dụng (lưu ý rằng đây không phải là trường mã nhận dạng) được cung cấp trong nguồn cấp dữ liệu của nhà cung cấp nội dung nghe nhìn đã xuất bản lên Google TV.Name: Đây là thông tin phụ trợ và được dùng để so khớp quyền sử dụng. Mặc dù không bắt buộc, nhưng việc cung cấp tên quyền sử dụng mà con người có thể đọc được sẽ giúp cả nhà phát triển và nhóm hỗ trợ hiểu rõ hơn về quyền sử dụng của người dùng. Ví dụ: Sling Orange.ExpirationTimeMillis: Bạn có thể chỉ định thời gian hết hạn tính bằng mili giây cho quyền sử dụng này, nếu thời gian này khác với thời gian hết hạn của gói thuê bao. Theo mặc định, quyền sử dụng sẽ hết hạn khi gói thuê bao hết hạn.
Đối với đoạn mã nguồn cấp dữ liệu mẫu của nhà cung cấp nội dung nghe nhìn sau:
"actionAccessibilityRequirement": [
{
"@type": "ActionAccessSpecification",
"category": "subscription",
"availabilityStarts": "2022-06-01T07:00:00Z",
"availabilityEnds": "2026-05-31T07:00:00Z",
"requiresSubscription": {
"@type": "MediaSubscription",
// Don't match this string,
// ID is only used to for reconciliation purpose
"@id": "https://www.example.com/971bfc78-d13a-4419",
// Don't match this, as name is only used for displaying purpose
"name": "Example entitlement name",
"commonTier": false,
// match this identifier in your API. This is the crucial
// entitlement identifier used for recommendation purpose.
"identifier": "example.com:entitlementString1"
}
Ví dụ sau đây sẽ tạo một SubscriptionEntity cho người dùng đã đăng ký:
// Subscription with entitlements.
// The entitlement expires at the same time as its subscription.
val subscription = SubscriptionEntity.Builder()
.setSubscriptionType(
SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
)
.setProviderPackageName("com.google.android.example")
// Optional
// December 30, 2025 12:00:00AM in milliseconds
.setExpirationTimeMillis(1767052800000)
.addEntitlement(
SubscriptionEntitlement.Builder()
// matches with the identifier in media provider feed
.setEntitlementId("example.com:entitlementString1")
.setDisplayName("entitlement name1")
.build()
)
.build()
// Subscription with entitlements
// The entitement has different expiration time from its subscription
val subscription = SubscriptionEntity.Builder()
.setSubscriptionType(
SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
)
.setProviderPackageName("com.google.android.example")
// Optional
// December 30, 2025 12:00:00AM in milliseconds
.setExpirationTimeMillis(1767052800000)
.addEntitlement(
SubscriptionEntitlement.Builder()
.setEntitlementId("example.com:entitlementString1")
.setDisplayName("entitlement name1")
// You may set the expiration time for entitlement
// December 15, 2025 10:00:00 AM in milliseconds
.setExpirationTimeMillis(1765792800000)
.build())
.build()
Gói thuê bao cho gói dịch vụ được liên kết
Mặc dù gói thuê bao thường thuộc về nhà cung cấp nội dung nghe nhìn của ứng dụng gốc, nhưng bạn có thể gán một gói thuê bao cho một gói dịch vụ được liên kết bằng cách chỉ định tên gói dịch vụ được liên kết trong gói thuê bao.
Mã mẫu sau đây minh hoạ cách tạo gói thuê bao của người dùng.
// Subscription for linked service package
val subscription = SubscriptionEntity.Builder()
.setSubscriptionType(
SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
)
.setProviderPackageName("com.google.android.example")
// Optional
// December 30, 2025 12:00:00AM in milliseconds since epoch
.setExpirationTimeMillis(1767052800000)
.build()
Ngoài ra, nếu người dùng có một gói thuê bao khác cho một dịch vụ phụ, hãy thêm một gói thuê bao khác và đặt tên gói dịch vụ được liên kết cho phù hợp.
// Subscription for linked service package
val linkedSubscription = Subscription.Builder()
.setSubscriptionType(
SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
)
.setProviderPackageName("linked service package name")
// Optional
// December 30, 2025 12:00:00AM in milliseconds since epoch
.setExpirationTimeMillis(1767052800000)
.addBundledSubscription(
BundledSubscription.Builder()
.setBundledSubscriptionProviderPackageName(
"bundled-subscription-package-name"
)
.setSubscriptionType(SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE)
.setExpirationTimeMillis(111)
.addEntitlement(
SubscriptionEntitlement.Builder()
.setExpirationTimeMillis(111)
.setDisplayName("Silver subscription")
.setEntitlementId("subscription.tier.platinum")
.build()
)
.build()
)
.build()
Bạn cũng có thể thêm quyền sử dụng vào gói thuê bao dịch vụ được liên kết.
Cung cấp tập hợp gói thuê bao
Chạy công việc xuất bản nội dung trong khi ứng dụng đang chạy ở nền trước.
Sử dụng phương thức publishSubscriptionCluster() từ lớp
AppEngagePublishClient để xuất bản đối tượng SubscriptionCluster.
Hãy nhớ khởi chạy ứng dụng và kiểm tra xem dịch vụ có hoạt động hay không như mô tả trong hướng dẫn Bắt đầu sử dụng.
client.publishSubscription(
PublishSubscriptionRequest.Builder()
.setAccountProfile(accountProfile)
.setSubscription(subscription)
.build()
)
Sử dụng setSubscription() để xác minh rằng người dùng chỉ nên có một gói thuê bao cho dịch vụ.
Sử dụng addLinkedSubscription() hoặc addLinkedSubscriptions() (chấp nhận danh sách các gói thuê bao được liên kết) để cho phép người dùng có từ 0 gói thuê bao được liên kết trở lên.
Khi dịch vụ nhận được yêu cầu, một mục mới sẽ được tạo và mục cũ sẽ tự động bị xoá sau 60 ngày. Hệ thống luôn sử dụng mục mới nhất. Trong trường hợp xảy ra lỗi, toàn bộ yêu cầu sẽ bị từ chối và trạng thái hiện tại sẽ được duy trì.
Luôn cập nhật gói thuê bao
Để cung cấp thông tin cập nhật ngay khi có thay đổi, hãy gọi
publishSubscriptionClusterbất cứ khi nào trạng thái gói thuê bao của người dùng thay đổi, chẳng hạn như kích hoạt, huỷ kích hoạt, nâng cấp, hạ cấp.Để xác thực thường xuyên nhằm đảm bảo độ chính xác liên tục, hãy gọi
publishSubscriptionClusterít nhất mỗi tháng một lần.Để xoá dữ liệu Engage, hãy xoá dữ liệu của người dùng theo cách thủ công khỏi máy chủ Google TV trước khoảng thời gian lưu giữ tiêu chuẩn là 60 ngày, sử dụng phương thức
client.deleteClusters. Thao tác này sẽ xoá tất cả dữ liệu Engage hiện có cho hồ sơ tài khoản hoặc cho toàn bộ tài khoản, tuỳ thuộc vàoDeleteReasonđã cho.Đoạn mã sau đây cho thấy cách xoá một gói thuê bao của người dùng:
// If the user logs out from your media app, you must make the following call // to remove subscription and other Engage data from the current // google TV device. client.deleteClusters( new DeleteClustersRequest.Builder() .setAccountProfile(accountProfile) .setReason(DeleteReason.DELETE_REASON_USER_LOG_OUT) .build() )Đoạn mã sau đây minh hoạ việc xoá gói thuê bao của người dùng khi người dùng thu hồi sự đồng ý:
// If the user revokes the consent to share across device, make the call // to remove subscription and other Engage data from all google // TV devices. client.deleteClusters( new DeleteClustersRequest.Builder() .setAccountProfile(accountProfile) .setReason(DeleteReason.DELETE_REASON_LOSS_OF_CONSENT) .build() )Mã sau đây minh hoạ cách xoá dữ liệu về gói thuê bao khi xoá hồ sơ người dùng.
// If the user delete a specific profile, you must make the following call // to remove subscription data and other Engage data. client.deleteClusters( new DeleteClustersRequest.Builder() .setAccountProfile(accountProfile) .setReason(DeleteReason.DELETE_REASON_ACCOUNT_PROFILE_DELETION) .build() )
Thử nghiệm
Phần này cung cấp hướng dẫn từng bước để thử nghiệm việc triển khai gói thuê bao. Xác minh độ chính xác của dữ liệu và chức năng phù hợp trước khi ra mắt.
Danh sách kiểm tra tích hợp xuất bản
Quá trình xuất bản sẽ diễn ra khi ứng dụng đang chạy ở nền trước và người dùng đang tương tác tích cực với ứng dụng.
Xuất bản khi:
- Người dùng đăng nhập lần đầu tiên.
- Người dùng thay đổi hồ sơ (nếu ứng dụng hỗ trợ hồ sơ).
- Người dùng mua gói thuê bao mới.
- Người dùng nâng cấp gói thuê bao.
- Gói thuê bao của người dùng hết hạn.
Kiểm tra xem ứng dụng có đang gọi đúng các API
isServiceAvailable()vàpublishClusters()trong logcat hay không, trong các sự kiện xuất bản.Xác minh rằng dữ liệu hiển thị trong ứng dụng xác minh. Ứng dụng xác minh sẽ hiển thị gói thuê bao dưới dạng một hàng riêng biệt. Khi API xuất bản được gọi, dữ liệu sẽ xuất hiện trong ứng dụng xác minh.
Chuyển đến ứng dụng và thực hiện từng thao tác sau:
- Đăng nhập.
- Chuyển đổi giữa các hồ sơ (nếu được hỗ trợ).
- Mua một gói thuê bao mới.
- Nâng cấp một gói thuê bao hiện có.
- Làm cho gói thuê bao hết hạn.
Xác minh hoạt động tích hợp
Để thử nghiệm hoạt động tích hợp, hãy sử dụng ứng dụng xác minh.
- Đối với từng sự kiện, hãy kiểm tra xem ứng dụng có gọi API
publishSubscriptionhay không. Xác minh dữ liệu đã xuất bản trong ứng dụng xác minh. Xác minh rằng mọi thứ đều có màu xanh lục trong ứng dụng xác minh Nếu tất cả thông tin của thực thể đều chính xác, thì tất cả thực thể sẽ hiển thị dấu kiểm màu xanh lục "All Good" (Tất cả đều tốt).
Hình 1. Gói thuê bao thành công Các vấn đề cũng được làm nổi bật trong ứng dụng xác minh
Hình 2.Gói thuê bao không thành công Để xem các vấn đề trong gói thuê bao đi kèm, hãy dùng điều khiển từ xa của TV để tập trung vào gói thuê bao đi kèm cụ thể đó rồi nhấp để xem các vấn đề. Trước tiên, bạn có thể phải tập trung vào hàng rồi di chuyển sang phải để tìm thẻ Gói thuê bao đi kèm. Các vấn đề được làm nổi bật bằng màu đỏ như trong Hình 3. Ngoài ra, hãy dùng điều khiển từ xa để di chuyển xuống để xem các vấn đề trong quyền sử dụng trong gói thuê bao đi kèm
Hình 3.Lỗi gói thuê bao Để xem các vấn đề trong quyền sử dụng, hãy dùng điều khiển từ xa của TV để tập trung vào quyền sử dụng cụ thể đó rồi nhấp để xem các vấn đề. Các vấn đề được làm nổi bật bằng màu đỏ.
Hình 4.Thông tin chi tiết về lỗi gói thuê bao