Membagikan Hak Aplikasi dengan Google TV Menggunakan Engage SDK

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

Panduan ini berisi petunjuk bagi developer untuk membagikan data langganan dan hak aplikasi ke Google TV menggunakan Engage SDK. Pengguna dapat menemukan konten yang berhak mereka akses dan mengaktifkan Google TV untuk memberikan rekomendasi konten yang sangat relevan kepada pengguna, langsung dalam pengalaman Google TV di TV, perangkat seluler, dan tablet.

Prasyarat

Anda harus mengaktifkan feed tindakan media sebelum dapat menggunakan Device Entitlement API. Jika Anda belum melakukannya, selesaikan proses aktivasi feed tindakan media.

Persiapan

Selesaikan petunjuk Persiapan dalam panduan Memulai.

  1. Publikasikan informasi langganan pada peristiwa berikut:
    1. Pengguna login ke aplikasi Anda.
    2. Pengguna beralih antar-profil (jika profil didukung).
    3. Pengguna membeli langganan baru.
    4. Pengguna mengupgrade langganan yang ada.
    5. Masa berlaku langganan pengguna berakhir.

Integrasi

Bagian ini memberikan contoh kode dan petunjuk yang diperlukan untuk menerapkan SubscriptionEntity guna mengelola berbagai jenis langganan.

Langganan tingkat umum

Untuk pengguna dengan langganan dasar ke layanan penyedia media, misalnya, layanan yang memiliki satu tingkat langganan yang memberikan akses ke semua konten berbayar, berikan detail penting berikut:

  1. SubscriptionType: Tunjukkan dengan jelas paket langganan tertentu yang dimiliki pengguna.

    • SUBSCRIPTION_TYPE_ACTIVE: Pengguna memiliki langganan berbayar yang aktif.
    • SUBSCRIPTION_TYPE_ACTIVE_TRIAL: Pengguna memiliki langganan uji coba.
    • SUBSCRIPTION_TYPE_INACTIVE: Pengguna memiliki akun, tetapi tidak memiliki langganan atau uji coba yang aktif.

  2. ExpirationTimeMillis: Waktu opsional dalam milidetik. Tentukan kapan langganan akan berakhir.

  3. ProviderPackageName: Tentukan nama paket aplikasi yang menangani langganan.

Contoh untuk feed penyedia media contoh.

"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
  }

Contoh berikut membuat SubscriptionEntity untuk pengguna:

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()

Langganan premium

Jika penawaran aplikasi memiliki paket langganan premium bertingkat, yang mencakup konten atau fitur yang diperluas di luar tingkat umum, tunjukkan hal ini dengan menambahkan satu atau beberapa hak ke Langganan.

Hak ini memiliki kolom berikut:

  1. Identifier: String ID yang diperlukan untuk hak ini. Nilai ini harus cocok dengan salah satu ID hak (perhatikan bahwa ini bukan kolom ID) yang disediakan di feed penyedia media yang dipublikasikan ke Google TV.
  2. Name: Ini adalah informasi tambahan dan digunakan untuk pencocokan hak. Meskipun bersifat opsional, memberikan nama hak yang dapat dibaca manusia akan meningkatkan pemahaman tentang hak pengguna bagi developer dan tim dukungan. Misalnya: Sling Orange.
  3. ExpirationTimeMillis: Secara opsional, tentukan waktu habis masa berlaku dalam milidetik untuk hak ini, jika berbeda dengan waktu habis masa berlaku langganan. Secara default, masa berlaku hak akan berakhir bersama dengan masa berlaku langganan.

Untuk cuplikan feed penyedia media contoh berikut:

"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"
  }

Contoh berikut membuat SubscriptionEntity untuk pengguna yang berlangganan:

// 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()

Langganan untuk paket layanan tertaut

Meskipun langganan biasanya dimiliki oleh penyedia media aplikasi asal, langganan dapat diatribusikan ke paket layanan tertaut dengan menentukan nama paket layanan tertaut dalam langganan.

Contoh kode berikut menunjukkan cara membuat langganan pengguna.

// 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()

Selain itu, jika pengguna memiliki langganan lain ke layanan anak perusahaan, tambahkan langganan lain dan tetapkan nama paket layanan tertaut yang sesuai.

// 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()

Anda juga dapat menambahkan hak ke langganan layanan tertaut.

Menyediakan set langganan

Jalankan tugas publikasi konten saat aplikasi berada di latar depan.

Gunakan metode publishSubscriptionCluster(), dari class AppEngagePublishClient, untuk memublikasikan objek SubscriptionCluster.

Pastikan untuk menginisialisasi klien dan memeriksa ketersediaan layanan seperti yang dijelaskan dalam Panduan memulai.

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

Gunakan setSubscription() untuk memverifikasi bahwa pengguna hanya boleh memiliki satu langganan ke layanan.

Gunakan addLinkedSubscription(), atau addLinkedSubscriptions() yang menerima daftar langganan tertaut, untuk memungkinkan pengguna memiliki nol atau lebih langganan tertaut.

Saat layanan menerima permintaan, entri baru akan dibuat dan entri lama akan otomatis dihapus setelah 60 hari. Sistem selalu menggunakan entri terbaru. Jika terjadi error, seluruh permintaan akan ditolak dan status yang ada dipertahankan.

Memastikan langganan selalu terbaru

  1. Untuk memberikan update langsung saat terjadi perubahan, panggil publishSubscriptionCluster setiap kali status langganan pengguna berubah seperti aktivasi, penonaktifan, upgrade, downgrade.

  2. Untuk memberikan validasi rutin atas akurasi berkelanjutan, panggil publishSubscriptionCluster setidaknya sekali per bulan.

  3. Untuk menghapus data Penemuan video, hapus data pengguna secara manual dari server Google TV sebelum periode retensi standar 60 hari, gunakan metode client.deleteClusters. Tindakan ini akan menghapus semua data penemuan video yang ada untuk profil akun, atau untuk seluruh akun, bergantung pada DeleteReason yang diberikan.

    Cuplikan kode berikut menunjukkan cara menghapus langganan pengguna:

    // 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()
  )

    Cuplikan kode berikut menunjukkan penghapusan langganan pengguna saat pengguna mencabut izin:

    // 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()
)

    Kode berikut menunjukkan cara menghapus data langganan saat penghapusan profil pengguna.

    // 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()
)

Pengujian

Bagian ini memberikan panduan langkah demi langkah untuk menguji penerapan langganan. Verifikasi akurasi data dan fungsi yang tepat sebelum peluncuran.

Checklist Publikasikan Integrasi

  1. Publikasi harus terjadi saat aplikasi berada di latar depan dan pengguna berinteraksi secara aktif dengannya.

  2. Publikasikan saat:

    • Pengguna login untuk pertama kalinya.
    • Pengguna mengubah profil (jika profil didukung).
    • Pengguna membeli langganan baru.
    • Pengguna mengupgrade langganan.
    • Masa berlaku langganan pengguna berakhir.

  3. Periksa apakah aplikasi memanggil API isServiceAvailable() dan publishClusters() dengan benar di logcat, saat memublikasikan peristiwa.

  4. Pastikan data terlihat di aplikasi verifikasi. Aplikasi verifikasi harus menampilkan langganan sebagai baris terpisah. Saat API publikasi dipanggil, data akan muncul di aplikasi verifikasi.

  5. Buka aplikasi dan lakukan setiap tindakan berikut:

    • Login.
    • Beralih antar-profil (jika didukung).
    • Beli langganan baru.
    • Mengupgrade langganan yang ada.
    • Mengakhiri masa berlaku langganan.

Verifikasi integrasi

Untuk menguji integrasi Anda, gunakan aplikasi verifikasi.

  1. Untuk setiap peristiwa, periksa apakah aplikasi telah memanggil publishSubscription API. Verifikasi data yang dipublikasikan di aplikasi verifikasi. Pastikan semuanya berwarna hijau di aplikasi verifikasi

  2. Jika semua informasi entitas sudah benar, akan muncul tanda centang hijau "Semua Oke" di semua entitas.

    Screenshot Berhasil Aplikasi Verifikasi
    Gambar 1. Berhasil berlangganan

  3. Masalah juga ditandai di aplikasi verifikasi

    Screenshot Error Aplikasi Verifikasi
    Gambar 2.Berlangganan gagal

  4. Untuk melihat masalah dalam langganan paket, gunakan remote TV untuk memfokuskan langganan paket tertentu tersebut, lalu klik untuk melihat masalahnya. Anda mungkin harus memfokuskan baris terlebih dahulu dan berpindah ke kanan untuk menemukan kartu Langganan Paket. Masalah ditandai dengan warna merah seperti yang ditunjukkan pada Gambar 3. Selain itu, gunakan remote untuk berpindah ke bawah guna melihat masalah dalam hak di dalam langganan paket

    Screenshot Detail Error Aplikasi Verifikasi
    Gambar 3.Kesalahan Langganan

  5. Untuk melihat masalah dalam hak, gunakan remote TV untuk memfokuskan pada hak tertentu tersebut dan klik untuk melihat masalah. Masalah ditandai dengan warna merah.

    Screenshot Error Aplikasi Verifikasi
    Gambar 4.Detail Error Langganan