Membagikan Hak Aplikasi dengan Google TV Menggunakan Engage SDK

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

Prasyarat

Aktivasi feed tindakan media diperlukan sebelum Anda dapat menggunakan API hak perangkat. Jika Anda belum melakukannya, selesaikan proses aktivasi feed tindakan media.

Persiapan

Sebelum memulai, selesaikan langkah-langkah berikut Pastikan aplikasi Anda menargetkan API level 19 atau yang lebih tinggi untuk integrasi ini

  1. Tambahkan library com.google.android.engage ke aplikasi Anda:

    Ada SDK terpisah yang dapat digunakan dalam integrasi: satu untuk aplikasi seluler dan satu lagi untuk aplikasi TV.

    Untuk Perangkat Seluler

    
  dependencies {
    implementation 'com.google.android.engage:engage-core:1.5.5
  }

    untuk TV

    
  dependencies {
    implementation 'com.google.android.engage:engage-tv:1.0.2
  }

  2. Tetapkan lingkungan layanan Engage ke produksi dalam file AndroidManifest.xml.

    Untuk apk seluler

    
<meta-data
      android:name="com.google.android.engage.service.ENV"
      android:value="PRODUCTION">
</meta-data>

    Untuk APK TV

    
<meta-data
    android:name="com.google.android.engage.service.ENV"
    android:value="PRODUCTION">
</meta-data>

  3. Sebelum mengirim APK ke Google, tetapkan lingkungan layanan engage ke produksi dalam file AndroidManifest.xml Anda. Untuk performa yang optimal dan kompatibilitas di masa mendatang, publikasikan data hanya saat aplikasi berada di latar depan dan pengguna berinteraksi secara aktif dengannya, seperti peluncuran aplikasi, pasca-login, atau selama penggunaan aktif. Publikasi dari proses latar belakang tidak disarankan.

  4. 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 sudah ada.
    5. Masa berlaku langganan pengguna berakhir.

Integrasi

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

Akun dan profil pengguna

Untuk mengizinkan fitur yang dipersonalisasi di Google TV, berikan informasi akun. Gunakan AccountProfile untuk menyediakan:

  1. ID Akun: ID unik yang mewakili akun pengguna. Ini dapat berupa ID akun yang sebenarnya atau versi yang di-obfuscate dengan benar.
// Set the account ID to which the subscription applies.
// Don't set the profile ID because subscription applies to account level.
val accountProfile = AccountProfile.Builder()
  .setAccountId("user_account_id")
  .setProfileId("user_profile id")
  .build();

Langganan tingkat umum

Untuk pengguna yang memiliki 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. Jenis langganan: Tunjukkan dengan jelas paket langganan tertentu yang dimiliki pengguna.

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

  2. Waktu habis masa berlaku: Waktu opsional dalam milidetik. Tentukan kapan langganan akan berakhir masa berlakunya.

  3. Nama paket penyedia: 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 aplikasi menawarkan paket langganan premium multi-tingkat, yang mencakup konten atau fitur yang diperluas di luar tingkat umum, tampilkan hal ini dengan menambahkan satu atau beberapa hak ke Langganan.

Hak ini memiliki kolom berikut:

  1. ID: String ID yang diperlukan untuk hak ini. ID ini harus cocok dengan salah satu ID hak (perhatikan bahwa ini bukan kolom ID) yang diberikan di feed penyedia media yang dipublikasikan ke Google TV.
  2. Nama: 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. Expiration TimeMillis: Secara opsional, tentukan waktu habis masa berlaku dalam milidetik untuk hak ini, jika berbeda dengan waktu habis masa berlaku langganan. Secara default, hak akan berakhir dengan berakhirnya langganan.

Untuk contoh cuplikan feed penyedia media 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 milik 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 sebagaimana mestinya.

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

Secara opsional, tambahkan hak ke langganan layanan tertaut juga.

Memberikan kumpulan langganan

Jalankan tugas publikasi konten saat aplikasi berada di latar depan.

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

Gunakan isServiceAvailable untuk memeriksa apakah layanan tersedia untuk integrasi.

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

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

Gunakan addLinkedSubscription(), atau addLinkedSubscriptions() yang menerima daftar langganan tertaut, untuk memungkinkan pengguna memiliki nol atau beberapa 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 pembaruan langsung setelah perubahan, panggil publishSubscriptionCluster() setiap kali status langganan pengguna berubah seperti aktivasi, penonaktifan, upgrade, downgrade.

  2. Untuk memberikan validasi rutin guna akurasi yang 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 untuk 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
          .Builder()
          .setAccountId()
          .setProfileId()
          .build()
      )
    .setReason(DeleteReason.DELETE_REASON_USER_LOG_OUT)
    .build()
    )
  ```
Following code snippet demonstrates removal of user subscription
when user revokes the consent.

```Kotlin
  // 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
        .Builder()
        .setAccountId()
        .setProfileId()
        .build()
      )
      .setReason(DeleteReason.DELETE_REASON_LOSS_OF_CONSENT)
      .build()
  )
  ```

Following code demonstrates how to remove subscription data on user profile
deletion.

```Kotlin
// 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
    .Builder()
    .setAccountId()
    .setProfileId()
    .build()
  )
  .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 Publikasi Integrasi

  1. Publikasi harus terjadi saat aplikasi berada di latar depan dan pengguna secara aktif berinteraksi 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, pada peristiwa publikasi.

  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.

    • Pastikan Engage Service Flag TIDAK disetel ke produksi dalam file Manifes Android aplikasi.
    • Instal dan buka aplikasi Engage Verification.
    • Jika nilai isServiceAvailable adalah false di aplikasi verifikasi, klik tombol Toggle dalam aplikasi verifikasi untuk menyetelnya ke true.
    • Masukkan nama paket aplikasi. Tindakan ini akan otomatis menampilkan data yang dipublikasikan.

  5. Buka aplikasi dan lakukan setiap tindakan berikut:

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

Memverifikasi integrasi

Untuk menguji integrasi Anda, gunakan aplikasi verifikasi.

Aplikasi verifikasi adalah aplikasi Android yang dapat digunakan developer untuk memverifikasi bahwa integrasi berfungsi. Aplikasi menyertakan kemampuan untuk membantu developer memverifikasi intent siaran dan data. Hal ini membantu memverifikasi akurasi data dan fungsi yang tepat sebelum peluncuran.

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

  2. Jika semua informasi entitas sudah benar, entitas tersebut akan menampilkan tanda centang hijau "Semua Baik" di semua entitas.

    Screenshot Aplikasi Verifikasi Berhasil
    Gambar 1. Langganan berhasil

  3. Masalah juga ditandai di aplikasi verifikasi

    Screenshot Error Aplikasi Verifikasi
    Gambar 2.Langganan tidak berhasil

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

    Screenshot Detail Error Aplikasi Verifikasi
    Gambar 3.Error Langganan

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

    Screenshot Error Aplikasi Verifikasi
    Gambar 4.Detail Error Langganan