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 dapatkan 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
Mengaktifkan feed tindakan media diperlukan sebelum Anda dapat menggunakan Device Entitlement API. 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
Tambahkan library
com.google.android.engageke aplikasi Anda:Ada SDK terpisah untuk digunakan dalam integrasi: satu untuk aplikasi seluler dan satu 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 }Setel 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>APK untuk TV
<meta-data android:name="com.google.android.engage.service.ENV" android:value="PRODUCTION"> </meta-data>Sebelum mengirim APK ke Google, tetapkan lingkungan layanan engagement ke produksi di 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, setelah login, atau selama penggunaan aktif. Publikasi dari proses latar belakang tidak disarankan.
Publikasikan informasi langganan pada peristiwa berikut:
- Pengguna login ke aplikasi Anda.
- Pengguna beralih antar-profil (jika profil didukung).
- Pengguna membeli langganan baru.
- Pengguna mengupgrade langganan yang ada.
- Masa berlaku langganan pengguna berakhir.
Integrasi
Bagian ini memberikan contoh kode dan petunjuk 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 memberikan:
- ID Akun: ID unik yang mewakili akun pengguna. Ini dapat berupa ID akun sebenarnya atau versi yang disamarkan dengan tepat.
// 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 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:
Jenis langganan: 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.
Waktu habis masa berlaku: Waktu opsional dalam milidetik. Tentukan kapan langganan akan berakhir.
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 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:
- ID: String ID yang diperlukan untuk hak ini. Nilai 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.
- 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.
- 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 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 termasuk dalam 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();
Secara opsional, tambahkan hak ke langganan layanan tertaut juga.
Menyediakan set 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 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
- Untuk memberikan update langsung saat terjadi perubahan, panggil
publishSubscriptionCluster()setiap kali status langganan pengguna berubah seperti aktivasi, penonaktifan, upgrade, downgrade. Untuk memberikan validasi rutin atas akurasi berkelanjutan, panggil
publishSubscriptionCluster()setidaknya sekali per bulan.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 padaDeleteReasonyang 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 Publikasikan Integrasi
Publikasi harus terjadi saat aplikasi berada di latar depan dan pengguna berinteraksi secara aktif dengannya.
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.
Periksa apakah aplikasi memanggil API
isServiceAvailable()danpublishClusters()dengan benar di logcat, saat memublikasikan peristiwa.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 di file Manifes Android aplikasi.
- Instal dan buka aplikasi Verifikasi Engagement.
- Jika nilai
isServiceAvailableadalahfalsedi aplikasi verifikasi, klik tombolToggledalam aplikasi verifikasi untuk menyetelnya ketrue. - Masukkan nama paket aplikasi. Data yang dipublikasikan akan otomatis ditampilkan.
Buka aplikasi dan lakukan setiap tindakan berikut:
- Login.
- beralih antar-profil (jika didukung).
- Beli langganan baru.
- Mengupgrade langganan yang 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.
- Untuk setiap peristiwa, periksa apakah aplikasi telah memanggil
publishSubscriptionAPI. Verifikasi data yang dipublikasikan di aplikasi verifikasi. Pastikan semuanya berwarna hijau di aplikasi verifikasi Jika semua informasi entitas sudah benar, akan muncul tanda centang hijau "Semua Oke" di semua entitas.
Gambar 1. Berhasil berlangganan Masalah juga ditandai di aplikasi verifikasi
Gambar 2.Langganan gagal 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 dalam langganan paket
Gambar 3.Error Langganan Untuk melihat masalah dalam hak, gunakan remote TV untuk memfokuskan pada hak tertentu tersebut dan klik untuk melihat masalah. Masalah ditandai dengan warna merah.
Gambar 4.Detail Error Langganan
Download
Sebelum mendownload, Anda harus menyetujui persyaratan dan ketentuan berikut.