Chia sẻ Quyền trong ứng dụng với Google TV bằng Engage SDK

book_path: /distribute/other-docs/_book.yaml project_path: /distribute/other-docs/_project.yaml

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 của ứ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 truy cập và cho phép Google TV đưa ra 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 tham gia nguồn cấp dữ liệu hành động với nội dung nghe nhìn thì mới có thể dùng API quyền của thiết bị. Nếu bạn chưa hoàn tất, hãy hoàn tất quy trình tham gia nguồn cấp dữ liệu hành động đối với nội dung nghe nhìn.

Chuẩn bị trước

Hoàn thành hướng dẫn Công việc chuẩn bị trong hướng dẫn Bắt đầu sử dụng.

Xuất bản thông tin về gói thuê bao đối với các sự kiện sau:
1. Người dùng đăng nhập vào ứng dụng của bạn.
2. Người dùng chuyển đổi giữa các hồ sơ (nếu được hỗ trợ).
3. Người dùng mua một gói thuê bao mới.
4. Người dùng nâng cấp một gói thuê bao hiện có.
5. Gói thuê bao của người dùng hết hạn.

Tích hợp

Phần này cung cấp các ví dụ về mã 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 chung

Đối với người dùng có gói thuê bao cơ bản của dịch vụ cung cấp nội dung nghe nhìn, chẳng hạn như một dịch vụ có một cấp 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 thiết yếu sau:

SubscriptionType: Nêu rõ gói thuê bao cụ thể mà người dùng đang sử dụng.
- SUBSCRIPTION_TYPE_ACTIVE: Người dùng có gói thuê bao trả phí đang hoạt động.
- SUBSCRIPTION_TYPE_ACTIVE_TRIAL: Người dùng có gói thuê bao dùng thử.
- SUBSCRIPTION_TYPE_INACTIVE: Người dùng có tài khoản nhưng không có gói thuê bao hoặc gói dùng thử đang hoạt động.
Lưu ý quan trọng: Chỉ những người dùng có SUBSCRIPTION_TYPE_ACTIVE hoặc SUBSCRIPTION_TYPE_ACTIVE_TRIAL mới đủ điều kiện nhận đề xuất nội dung được cá nhân hoá dựa trên gói thuê bao của họ.
ExpirationTimeMillis: Thời gian không bắt buộc tính bằng mili giây. Nêu rõ thời điểm gói thuê bao hết hạn.
ProviderPackageName: Chỉ định 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 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 đăng ký trả phí

Nếu ứng dụng cung cấp các gói thuê bao cao cấp nhiều cấp, bao gồm nội dung hoặc tính năng mở rộng ngoài cấp thông thường, hãy thể hiện điều này bằng cách thêm một hoặc nhiều quyền vào gói thuê bao.

Quyền này có các trường sau:

Identifier: Chuỗi giá trị nhận dạng bắt buộc cho quyền 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 (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 được xuất bản trên Google TV.
Name: Đây là thông tin phụ và được dùng để so khớp quyền. Mặc dù không bắt buộc, nhưng việc cung cấp tên quyền dễ đọc giúp cả nhà phát triển và nhóm hỗ trợ hiểu rõ hơn về quyền 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 này, nếu thời gian đó khác với thời gian hết hạn của gói thuê bao. Theo mặc định, quyền 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 sau đây 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": "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 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 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ể phân bổ 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 cho gói thuê bao dịch vụ được liên kết (không bắt buộc).

Cung cấp bộ thuê bao

Chạy tác vụ 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() của lớp AppEngagePublishClient để xuất bản đối tượng SubscriptionCluster.

Đảm bảo bạn khởi động ứ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.

client.publishSubscription(
  PublishSubscriptionRequest.Builder()
    .setAccountProfile(accountProfile)
    .setSubscription(subscription)
    .build()
  )

Sử dụng setSubscription() để xác minh rằng người dùng chỉ có một gói thuê bao cho dịch vụ.

Sử dụng addLinkedSubscription() hoặc addLinkedSubscriptions() (chấp nhận một 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 nhập 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 lập tức khi có thay đổi, hãy gọi publishSubscriptionCluster bấ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ột lần mỗi tháng.

Lưu ý: Vì Google TV tự động xoá dữ liệu cũ hơn 60 ngày để bảo vệ quyền riêng tư của người dùng, nên việc xuất bản dữ liệu đăng ký của người dùng ít nhất một lần mỗi tháng sẽ xác minh tính hợp lệ của dữ liệu. Không giống như publishContinuationCluster đối với dữ liệu xem tiếp, đừng đặt cờ syncAcrossDevices, vì thông tin về gói thuê bao được dùng theo mặc định để cung cấp nội dung trên tất cả các thiết bị.

Để xoá dữ liệu Khám phá video, 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 thời hạn lưu giữ tiêu chuẩn là 60 ngày bằng phương thức client.deleteClusters. Thao tác này sẽ xoá tất cả dữ liệu hiện có về video khám phá cho hồ sơ tài khoản hoặc cho toàn bộ tài khoản, tuỳ thuộc vào DeleteReason đã cho.

Đoạn mã sau đây cho thấy cách xoá 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 video discovery 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ạ cách xoá thông tin đăng ký 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 video discovery data from all google
// TV devices.
client.deleteClusters(
  new DeleteClustersRequest.Builder()
    .setAccountProfile(accountProfile)
    .setReason(DeleteReason.DELETE_REASON_LOSS_OF_CONSENT)
    .build()
)

Đoạn mã sau đây minh hoạ cách xoá dữ liệu 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 video discovery 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 để kiểm thử 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.

Xuất bản danh sách kiểm tra tích hợp

Bạn nên xuất bản khi ứng dụng ở nền trước và người dùng đang tích cực tương tá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 được hỗ trợ).
- 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 API isServiceAvailable() và publishClusters() trong logcat hay không, khi xuất bản các sự kiệ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.

Lưu ý quan trọng: Xác minh rằng Cờ Engage Service không được đặt thành sản xuất.
Chuyển đến ứng dụng rồi 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 gói thuê bao mới.
- Nâng cấp gói thuê bao hiện có.
- Hết hạn gói thuê bao.

Xác minh quá trình tích hợp

Để kiểm thử quá trình tích hợp, hãy dùng ứng dụng xác minh.

Đối với mỗi sự kiện, hãy kiểm tra xem ứng dụng đã gọi API publishSubscription hay chưa. 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ì hệ thống sẽ hiển thị dấu kiểm màu xanh lục "Ổn cả" trong tất cả các thực thể.

Hình 1. Đăng ký 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.Đăng ký không thành công
Để xem các vấn đề trong gói thuê bao kết hợp, hãy dùng điều khiển từ xa của TV để chuyển tiêu điểm đến gói thuê bao kết hợp 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 và di chuyển sang phải để tìm thẻ Gói thuê bao. Các vấn đề được đánh dấu 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 dưới và xem các vấn đề về quyền trong gói thuê bao

Hình 3.Lỗi đăng ký
Để xem các vấn đề trong quyền, hãy dùng điều khiển từ xa của TV để tập trung vào quyền cụ thể đó rồi nhấp để xem các vấn đề. Các vấn đề được đánh dấu màu đỏ.

Hình 4.Thông tin chi tiết về lỗi đăng ký