Panduan integrasi Engage SDK untuk TV

Lanjutkan Menonton memanfaatkan cluster Lanjutan untuk menampilkan video yang belum selesai dan episode berikutnya yang akan ditonton dari season TV yang sama, dari beberapa aplikasi dalam satu pengelompokan UI. Anda dapat menampilkan entitas mereka di cluster lanjutan ini. Ikuti panduan ini untuk mempelajari cara meningkatkan engagement pengguna melalui pengalaman Lanjutkan Menonton menggunakan Engage SDK.

Persiapan

Sebelum Anda memulai, selesaikan langkah-langkah berikut:

1. Update ke Target API 19 atau yang lebih tinggi

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

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

   Ponsel

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

   TV

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

3. Setel lingkungan layanan Engage ke produksi dalam file AndroidManifest.xml.

   Ponsel

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

   TV

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

4. Tambahkan izin untuk WRITE_EPG_DATA untuk APK TV

   <uses-permission android:name="com.android.providers.tv.permission.WRITE_EPG_DATA" />
   

5. Verifikasi publikasi konten yang andal dengan menggunakan layanan latar belakang, seperti androidx.work, untuk penjadwalan.

6. Untuk memberikan pengalaman menonton yang lancar, publikasikan data lanjutkan menonton saat peristiwa ini terjadi:

   1. Login Pertama: Saat pengguna login untuk pertama kalinya, publikasikan data untuk memastikan histori penayangan mereka langsung tersedia.
   2. Pembuatan atau Pengalihan Profil (Aplikasi Multi-Profil): Jika aplikasi Anda mendukung beberapa profil, publikasikan data saat pengguna membuat atau beralih profil.
   3. Gangguan Pemutaran Video: Untuk membantu pengguna melanjutkan dari bagian terakhir yang mereka tonton, publikasikan data saat mereka menjeda atau menghentikan video, atau saat aplikasi keluar selama pemutaran.
   4. Pembaruan Panel Lanjutkan Menonton (Jika Didukung): Saat pengguna menghapus item dari panel Lanjutkan Menonton, tunjukkan perubahan tersebut dengan memublikasikan data yang diperbarui.
   5. Penyelesaian Video:
      1. Untuk film, hapus film yang telah selesai ditonton dari panel Lanjutkan Menonton. Jika film adalah bagian dari serial, tambahkan film berikutnya untuk terus menarik perhatian pengguna.
      2. Untuk episode, hapus episode yang telah selesai dan tambahkan episode berikutnya dalam serial, jika tersedia, untuk mendorong penayangan berkelanjutan.

Integrasi

AccountProfile

Untuk mengizinkan pengalaman "lanjutkan menonton" yang dipersonalisasi di Google TV, berikan informasi akun dan profil. Gunakan AccountProfile untuk memberikan:

1. ID Akun: ID unik yang mewakili akun pengguna dalam aplikasi Anda. ID ini dapat berupa ID akun yang sebenarnya atau versi yang di-obfuscate dengan tepat.

2. ID Profil (opsional): Jika aplikasi Anda mendukung beberapa profil dalam satu akun, berikan ID unik untuk profil pengguna tertentu (sekali lagi, nyata atau di-obfuscate).

// If your app only supports account
val accountProfile = AccountProfile.Builder()
    .setAccountId("your_users_account_id")
    .build()

// If your app supports both account and profile
val accountProfile = AccountProfile.Builder()
    .setAccountId("your_users_account_id")
    .setProfileId("your_users_profile_id")
    .build()

Membuat entity

SDK telah menentukan entity yang berbeda untuk mewakili setiap jenis item. Cluster kelanjutan mendukung entity berikut:

1. MovieEntity
2. TvEpisodeEntity
3. LiveStreamingVideoEntity
4. VideoClipEntity

Tentukan URI khusus platform dan gambar poster untuk entitas ini.

Selain itu, buat URI pemutaran untuk setiap platform—seperti Android TV, Android, atau iOS—jika Anda belum melakukannya. Jadi, saat pengguna melanjutkan menonton di setiap platform, aplikasi akan menggunakan URI pemutaran yang ditargetkan untuk memutar konten video.

// Required. Set this when you want continue watching entities to show up on
// Google TV
val playbackUriTv = PlatformSpecificUri.Builder()
    .setPlatformType(PlatformType.TYPE_ANDROID_TV)
    .setActionUri(Uri.parse("https://www.example.com/entity_uri_for_tv"))
    .build()

// Required. Set this when you want continue watching entities to show up on
// Google TV Android app, Entertainment Space, Playstore Widget
val playbackUriAndroid = PlatformSpecificUri.Builder()
    .setPlatformType(PlatformType.TYPE_ANDROID_MOBILE)
    .setActionUri(Uri.parse("https://www.example.com/entity_uri_for_android"))
    .build()

// Optional. Set this when you want continue watching entities to show up on
// Google TV iOS app
val playbackUriIos = PlatformSpecificUri.Builder()
    .setPlatformType(PlatformType.TYPE_IOS)
    .setActionUri(Uri.parse("https://www.example.com/entity_uri_for_ios"))
    .build()

val platformSpecificPlaybackUris =
    Arrays.asList(playbackUriTv, playbackUriAndroid, playbackUriIos)

Gambar poster memerlukan URI dan dimensi piksel (tinggi dan lebar). Menargetkan faktor bentuk yang berbeda dengan menyediakan beberapa gambar poster, tetapi pastikan semua gambar mempertahankan rasio aspek 16:9 dan tinggi minimum 200 piksel untuk tampilan yang benar dari entitas "Lanjutkan Menonton", terutama dalam Entertainment Space Google. Gambar dengan tinggi kurang dari 200 piksel mungkin tidak ditampilkan.

val images = Arrays.asList(
    Image.Builder()
        .setImageUri(Uri.parse("http://www.example.com/entity_image1.png"))
        .setImageHeightInPixel(300)
        .setImageWidthInPixel(169)
        .build(),
    Image.Builder()
        .setImageUri(Uri.parse("http://www.example.com/entity_image2.png"))
        .setImageHeightInPixel(640)
        .setImageWidthInPixel(360)
        .build()
    // Consider adding other images for different form factors
)

MovieEntity

Contoh ini menunjukkan cara membuat MovieEntity dengan semua kolom wajib:

val movieEntity = MovieEntity.Builder()
   .setWatchNextType(WatchNextType.TYPE_CONTINUE)
   .setName("Movie name")
   .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
   .addPosterImages(images)
   // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
   .setLastEngagementTimeMillis(1701388800000)
   // Suppose the duration is 2 hours, it is 72000000 in milliseconds
   .setDurationMills(72000000)
   // Suppose last playback offset is 1 hour, 36000000 in milliseconds
   .setLastPlayBackPositionTimeMillis(36000000)
   .build()

Dengan memberikan detail seperti genre dan rating konten, Google TV dapat menampilkan konten Anda dengan cara yang lebih dinamis dan menghubungkannya dengan penonton yang tepat.

val genres = Arrays.asList("Action", "Science fiction")
val rating1 = RatingSystem.Builder().setAgencyName("MPAA").setRating("PG-13").build()
val contentRatings = Arrays.asList(rating1)
val movieEntity = MovieEntity.Builder()
    ...
    .addGenres(genres)
    .addContentRatings(contentRatings)
    .build()

Entitas otomatis tetap tersedia selama 60 hari kecuali jika Anda menentukan waktu habis masa berlaku yang lebih singkat. Tetapkan masa berlaku kustom hanya jika Anda ingin entitas dihapus sebelum periode default ini.

// Set the expiration time to be now plus 30 days in milliseconds
val expirationTime = DisplayTimeWindow.Builder()
    .setEndTimestampMillis(now().toMillis()+2592000000).build()
val movieEntity = MovieEntity.Builder()
    ...
    .addAvailabilityTimeWindow(expirationTime)
    .build()

TvEpisodeEntity

Contoh ini menunjukkan cara membuat TvEpisodeEntity dengan semua kolom yang diperlukan:

val tvEpisodeEntity = TvEpisodeEntity.Builder()
    .setWatchNextType(WatchNextType.TYPE_CONTINUE)
    .setName("Episode name")
    .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
    .addPosterImages(images)
    // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
    .setLastEngagementTimeMillis(1701388800000)
    .setDurationMills(72000000) // 2 hours in milliseconds
    // 45 minutes and 15 seconds in milliseconds is 2715000
    .setLastPlayBackPositionTimeMillis(2715000)
    .setEpisodeNumber("2")
    .setSeasonNumber("1")
    .setShowTitle("Title of the show")
    .build()

String nomor episode (seperti "2"), dan string nomor season (seperti "1") akan diubah ke bentuk yang tepat sebelum ditampilkan di kartu lanjutkan menonton. Perhatikan bahwa nilai ini harus berupa string numerik, jangan masukkan "e2", atau "episode 2", atau "s1" atau "season 1".

Jika acara TV tertentu memiliki satu season, tetapkan nomor season sebagai 1.

Untuk memaksimalkan peluang penonton menemukan konten Anda di Google TV, pertimbangkan untuk memberikan data tambahan seperti genre, rating konten, dan jangka waktu ketersediaan, karena detail ini dapat meningkatkan opsi tampilan dan pemfilteran.

val genres = Arrays.asList("Action", "Science fiction")
val rating1 = RatingSystem.Builder().setAgencyName("MPAA").setRating("PG-13").build()
val contentRatings = Arrays.asList(rating1)
val tvEpisodeEntity = TvEpisodeEntity.Builder()
    ...
    .addGenres(genres)
    .addContentRatings(contentRatings)
    .setSeasonTitle("Season Title")
    .setShowTitle("Show Title")
    .build()

VideoClipEntity

Berikut adalah contoh pembuatan VideoClipEntity dengan semua kolom wajib diisi.

VideoClipEntity merepresentasikan klip buatan pengguna seperti video YouTube.

val videoClipEntity = VideoClipEntity.Builder()
    .setPlaybackUri(Uri.parse("https://www.example.com/uri_for_current_platform")
    .setWatchNextType(WatchNextType.TYPE_CONTINUE)
    .setName("Video clip name")
    .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
    .addPosterImages(images)
    // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
    .setLastEngagementTimeMillis(1701388800000)
    .setDurationMills(600000) //10 minutes in milliseconds
    .setLastPlayBackPositionTimeMillis(300000) //5 minutes in milliseconds
    .addContentRating(contentRating)
    .build()

Secara opsional, Anda dapat menetapkan pembuat, gambar pembuat, waktu pembuatan dalam milidetik, atau jangka waktu ketersediaan .

LiveStreamingVideoEntity

Berikut contoh pembuatan LiveStreamingVideoEntity dengan semua kolom wajib diisi.

val liveStreamingVideoEntity = LiveStreamingVideoEntity.Builder()
    .setPlaybackUri(Uri.parse("https://www.example.com/uri_for_current_platform")
    .setWatchNextType(WatchNextType.TYPE_CONTINUE)
    .setName("Live streaming name")
    .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
    .addPosterImages(images)
    // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
    .setLastEngagementTimeMillis(1701388800000)
    .setDurationMills(72000000) //2 hours in milliseconds
    .setLastPlayBackPositionTimeMillis(36000000) //1 hour in milliseconds
    .addContentRating(contentRating)
    .build()

Secara opsional, Anda dapat menetapkan waktu mulai, penyiar, ikon penyiar, atau jangka waktu ketersediaan untuk entitas live streaming.

Untuk mengetahui informasi mendetail tentang atribut dan persyaratan, lihat referensi API.

Menyediakan data cluster Lanjutan

AppEngagePublishClient bertanggung jawab untuk memublikasikan cluster Lanjutan. Anda menggunakan metode publishContinuationCluster() untuk memublikasikan objek ContinuationCluster.

Pertama, Anda harus menggunakan isServiceAvailable() untuk memeriksa apakah layanan tersedia untuk integrasi.

client.publishContinuationCluster(
    PublishContinuationClusterRequest
        .Builder()
        .setContinuationCluster(
            ContinuationCluster.Builder()
                .setAccountProfile(accountProfile)
                .addEntity(movieEntity1)
                .addEntity(movieEntity2)
                .addEntity(tvEpisodeEntity1)
                .addEntity(tvEpisodeEntity2)
                .setSyncAcrossDevices(true)
                .build()
        )
        .build()
)

Saat layanan menerima permintaan tersebut, tindakan berikut akan terjadi dalam satu transaksi:

• Data ContinuationCluster yang ada dari partner developer akan dihapus.
• Data dari permintaan akan diuraikan dan disimpan di ContinuationCluster yang diperbarui.

Jika terjadi error, seluruh permintaan akan ditolak dan status yang ada dipertahankan.

API publikasi adalah API penyisipan yang menggantikan konten yang sudah ada. Jika perlu memperbarui entity tertentu di ContinuationCluster, Anda harus memublikasikan semua entity lagi.

Data ContinuationCluster hanya boleh diberikan untuk akun dewasa. Publikasikan hanya jika AccountProfile milik orang dewasa.

Sinkronisasi lintas perangkat

Flag SyncAcrossDevices mengontrol apakah data ContinuationCluster pengguna disinkronkan di seluruh perangkat seperti TV, ponsel, tablet, dll. Sinkronisasi lintas perangkat dinonaktifkan secara default.

Nilai:

• benar: Data ContinuationCluster dibagikan di semua perangkat pengguna untuk pengalaman menonton yang lancar. Sebaiknya pilih opsi ini untuk mendapatkan pengalaman lintas perangkat terbaik.
• salah: Data ContinuationCluster dibatasi untuk perangkat saat ini.

Mendapatkan Izin:

Aplikasi media harus menyediakan setelan yang jelas untuk mengaktifkan/menonaktifkan sinkronisasi lintas perangkat. Jelaskan manfaatnya bagi pengguna dan simpan preferensi pengguna sekali saja, lalu terapkan di publishContinuationCluster dengan tepat.

// Example to allow cross device syncing.
client.publishContinuationCluster(
    PublishContinuationClusterRequest
        .Builder()
        .setContinuationCluster(
            ContinuationCluster.Builder()
                .setAccountProfile(accountProfile)
                .setSyncAcrossDevices(true)
                .build()
        )
        .build()
)

Untuk mendapatkan hasil maksimal dari fitur lintas-perangkat kami, verifikasi bahwa aplikasi mendapatkan izin pengguna dan aktifkan SyncAcrossDevices ke true. Hal ini memungkinkan konten disinkronkan dengan lancar di seluruh perangkat, sehingga menghasilkan pengalaman pengguna yang lebih baik dan peningkatan interaksi. Misalnya, partner yang menerapkan fitur ini mengalami peningkatan 40% pada klik "lanjutkan menonton" karena konten mereka ditampilkan di beberapa perangkat.

Menghapus data Penemuan video

Untuk menghapus data pengguna secara manual dari server Google TV sebelum periode retensi 60 hari standar, gunakan metode client.deleteClusters(). Setelah menerima permintaan, layanan akan menghapus semua data penemuan video yang ada untuk profil akun, atau untuk seluruh akun.

Enum DeleteReason menentukan alasan penghapusan data. Kode berikut menghapus data lanjutkan menonton saat logout.

// If the user logs out from your media app, you must make the following call
// to remove continue watching data from the current google TV device,
// otherwise, the continue watching data will persist on the current
// google TV device until 60 days later.
client.deleteClusters(
    DeleteClustersRequest.Builder()
        .setAccountProfile(AccountProfile())
        .setReason(DeleteReason.DELETE_REASON_USER_LOG_OUT)
        .setSyncAcrossDevices(true)
        .build()
)

Pengujian

Gunakan aplikasi verifikasi untuk memverifikasi bahwa integrasi Engage SDK berfungsi dengan benar. Aplikasi Android ini menyediakan alat untuk membantu Anda memverifikasi data dan mengonfirmasi bahwa intent siaran ditangani dengan benar.

Setelah memanggil API publikasi, konfirmasi bahwa data Anda dipublikasikan dengan benar dengan memeriksa aplikasi verifikasi. Cluster lanjutan Anda akan ditampilkan sebagai baris yang berbeda dalam antarmuka aplikasi.

• Tetapkan Engage Service Flag hanya untuk build non-produksi di file Manifes Android aplikasi Anda.
• Instal dan buka aplikasi Engage Verify
• Jika isServiceAvailable adalah false, klik tombol "Alihkan" untuk mengaktifkan.
• Masukkan nama paket aplikasi Anda untuk otomatis melihat data yang dipublikasikan setelah Anda mulai memublikasikan.
• Uji tindakan ini di aplikasi Anda:
  • Login.
  • Beralih antar-profil(jika berlaku).
  • Mulai, lalu jeda video, atau kembali ke halaman beranda.
  • Tutup aplikasi selama pemutaran video.
  • Menghapus item dari baris "Lanjutkan Menonton" (jika didukung).
• Setelah setiap tindakan, pastikan aplikasi Anda memanggil API publishContinuationClusters dan data ditampilkan dengan benar di aplikasi verifikasi.

• Aplikasi verifikasi akan menampilkan tanda centang "Semua Oke" berwarna hijau untuk entitas yang diterapkan dengan benar.

  

• Aplikasi verifikasi akan menandai entitas yang bermasalah.

  

• Untuk memecahkan masalah entitas yang error, gunakan remote TV Anda untuk memilih dan mengklik entitas di aplikasi verifikasi. Masalah tertentu akan ditampilkan dan ditandai dengan warna merah untuk ditinjau (lihat contoh di bawah).

  

REST API

Engage SDK menawarkan REST API untuk memberikan pengalaman menonton terus-menerus yang konsisten di seluruh platform non-Android seperti iOS, Roku TV. API ini memungkinkan developer memperbarui status "Lanjutkan Menonton" untuk pengguna yang memilih ikut serta dari platform non-Android.

Prasyarat

• Anda harus menyelesaikan integrasi berbasis Engage SDK di perangkat terlebih dahulu. Langkah penting ini membuat hubungan yang diperlukan antara ID pengguna Google dan AccountProfile aplikasi Anda.
• Akses dan Autentikasi API: Untuk melihat dan mengaktifkan API di Project Google Cloud, Anda harus melalui proses daftar yang diizinkan. Semua permintaan API memerlukan autentikasi.

Mendapatkan Akses

Agar dapat mengakses untuk melihat dan mengaktifkan API di Konsol Google Cloud, akun Anda harus terdaftar.

1. ID Pelanggan Google Workspace harus tersedia. Jika tidak tersedia, Anda mungkin perlu menyiapkan Google Workspace serta Akun Google yang ingin Anda gunakan untuk memanggil API.
2. Siapkan akun dengan Konsol Google Cloud menggunakan email yang terkait dengan Google Workspace.
3. Membuat project baru
4. Buat akun layanan untuk Autentikasi API. Setelah Anda membuat akun layanan, Anda akan memiliki dua item:
   • ID akun layanan.
   • File JSON dengan kunci akun layanan Anda. Jaga keamanan file ini, Anda akan memerlukannya untuk mengautentikasi klien ke API nanti.
5. Workspace dan Akun Google terkait kini dapat menggunakan REST API. Setelah perubahan diterapkan, Anda akan diberi tahu apakah API siap dipanggil oleh akun layanan Anda.
6. Ikuti langkah-langkah berikut untuk bersiap melakukan panggilan API yang didelegasikan.

Memublikasikan Cluster Lanjutan

Untuk memublikasikan Data Penemuan Video, lakukan permintaan POST ke API publishContinuationCluster menggunakan sintaksis berikut.

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/profiles/{profile_id}/publishContinuationCluster

Dalam hal ini:

• package_name: Nama paket penyedia media
• accountId: ID unik untuk akun pengguna di sistem Anda. Harus cocok dengan accountId yang digunakan di jalur dalam perangkat.
• profileId: ID unik untuk profil pengguna dalam akun di sistem Anda. ID ini harus cocok dengan profileId yang digunakan di jalur dalam perangkat.

URL untuk akun tanpa profil adalah:

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/publishContinuationCluster

Payload ke permintaan ditampilkan di kolom entities. entities mewakili daftar entitas konten yang dapat berupa MovieEntity atau TVEpisodeEntity. Ini adalah bidang yang wajib diisi.

Isi Permintaan

Kolom entities berisi masing-masing movieEntity dan tvEpisodeEntity.

Setiap objek dalam array entity harus berupa salah satu jenis MediaEntity yang tersedia, yaitu MovieEntity dan TvEpisodeEntity, beserta kolom umum dan khusus jenis.

Cuplikan kode berikut menampilkan payload isi permintaan untuk API publishContinuationCluster.

{
  "entities": [
    {
      "movieEntity": {
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "name": "Movie1",
        "platform_specific_playback_uris": [
          "https://www.example.com/entity_uri_for_android",
          "https://www.example.com/entity_uri_for_iOS"
        ],
        "poster_images": [
          "http://www.example.com/movie1_img1.png",
          "http://www.example.com/movie1_imag2.png"
        ],
        "last_engagement_time_millis": 864600000,
        "duration_millis": 5400000,
        "last_play_back_position_time_millis": 3241111
      }
    },
    {
      "tvEpisodeEntity": {
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "name": "TV SERIES EPISODE 1",
        "platform_specific_playback_uris": [
          "https://www.example.com/entity_uri_for_android",
          "https://www.example.com/entity_uri_for_iOS"
        ],
        "poster_images": [
          "http://www.example.com/episode1_img1.png",
          "http://www.example.com/episode1_imag2.png"
        ],
        "last_engagement_time_millis": 864600000,
        "duration_millis": 1800000,
        "last_play_back_position_time_millis": 2141231,
        "episode_display_number": "1",
        "season_number": "1",
        "show_title": "title"
      }
    }
  ]
}

Menghapus data penemuan video

Gunakan clearClusters API untuk menghapus data penemuan video.

Gunakan URL POST untuk menghapus entity dari data penemuan video. Untuk menghapus data cluster lanjutan, lakukan permintaan POST ke API clearClusters menggunakan sintaksis berikut.

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/profiles/{profile_id}/clearClusters

Dalam hal ini:

• package_name: Nama paket penyedia media.
• accountId: ID unik untuk akun pengguna di sistem Anda. Harus cocok dengan accountId yang digunakan di jalur dalam perangkat.
• profileId: ID unik untuk profil pengguna dalam akun di sistem Anda. ID ini harus cocok dengan profileId yang digunakan di jalur dalam perangkat.

Payload untuk clearClusters API hanya berisi satu kolom, reason, yang berisi DeleteReason yang menentukan alasan penghapusan data.

{
  "reason": "DELETE_REASON_LOSS_OF_CONSENT"
}

Pengujian

Setelah berhasil memposting data, gunakan akun pengujian pengguna untuk memverifikasi bahwa konten yang diharapkan muncul di baris "Lanjutkan Menonton" di platform Google yang ditargetkan seperti Google TV dan aplikasi seluler Google TV Android dan iOS.

Saat pengujian, izinkan penundaan propagasi yang wajar selama beberapa menit dan patuhi persyaratan menonton, seperti menonton sebagian film atau menyelesaikan satu episode. Lihat panduan Tonton Berikutnya untuk developer aplikasi untuk mengetahui detailnya.