Halaman ini diterjemahkan oleh Cloud Translation API.

Panduan integrasi Engage SDK untuk TV
Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

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 dalam cluster kelanjutan ini. Ikuti panduan ini untuk mempelajari cara meningkatkan engagement pengguna melalui pengalaman Lanjutkan Menonton menggunakan Engage SDK.

Langkah 1: 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.engage ke aplikasi Anda:

Ada SDK terpisah yang dapat digunakan dalam integrasi: satu untuk aplikasi seluler dan satu lagi 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
  }
```

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

Ponsel


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

TV


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

Menambahkan izin untuk WRITE_EPG_DATA untuk apk TV

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

Pastikan publikasi konten yang andal dengan menggunakan layanan latar belakang, seperti androidx.work, untuk penjadwalan.
Untuk memberikan pengalaman menonton yang lancar, publikasikan data lanjutkan menonton saat peristiwa ini terjadi:
1. Login Pertama: Saat pengguna login untuk pertama kalinya, memublikasikan data mereka akan memastikan histori tontonan 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. Hal ini memastikan setiap pengguna memiliki pengalaman yang dipersonalisasi.
3. Gangguan Pemutaran Video: Untuk membantu pengguna melanjutkan dari bagian yang terakhir diputar, publikasikan data saat mereka menjeda atau menghentikan video, atau saat aplikasi keluar selama pemutaran.
4. Pembaruan Baki Lanjutkan Menonton (Jika Didukung): Saat pengguna menghapus item dari baki Lanjutkan Menonton, tampilkan perubahan tersebut dengan memublikasikan data yang diperbarui. Hal ini memastikan baki tetap relevan dan dipersonalisasi.
5. Penyelesaian Video:
  1. Untuk film, hapus film yang telah selesai dari baki Teruskan Menonton. Jika film merupakan bagian dari serial, tambahkan film berikutnya agar pengguna tetap tertarik.
  2. Untuk episode, hapus episode yang telah selesai dan tambahkan episode berikutnya dalam serial, jika tersedia, untuk mendorong tontonan berkelanjutan.

Integrasi

AccountProfile

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

ID Akun: ID unik yang mewakili akun pengguna dalam aplikasi Anda. Ini dapat berupa ID akun yang sebenarnya atau versi yang di-obfuscate dengan benar.
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 lanjutan mendukung entity berikut:

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 terus 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). Targetkan 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 entitas "Lanjutkan Menonton" yang benar, terutama dalam Ruang Hiburan Google. Gambar dengan tinggi kurang dari 200 piksel mungkin tidak ditampilkan.


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

MovieEntity

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

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

Memberikan detail seperti genre dan rating konten akan memberi Google TV kemampuan untuk 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 akan otomatis tetap tersedia selama 60 hari, kecuali jika Anda menentukan waktu habis masa berlaku yang lebih singkat. Hanya tetapkan masa berlaku kustom jika Anda memerlukan entitas untuk dihapus sebelum periode default ini.

// Set the expiration time to be now plus 30 days in milliseconds
val expirationTime = new 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 diperluas ke bentuk yang tepat sebelum ditampilkan di kartu lanjutkan menonton. Perhatikan bahwa string 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, sebaiknya berikan data tambahan seperti genre, rating konten, dan periode waktu ketersediaan, karena detail ini dapat meningkatkan tampilan dan opsi 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 yang diperlukan.

VideoClipEntity mewakili 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 periode waktu ketersediaan .

LiveStreamingVideoEntity

Berikut adalah contoh pembuatan LiveStreamingVideoEntity dengan semua kolom yang diperlukan.

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

Jika ingin, Anda dapat menetapkan waktu mulai, penyiar, ikon penyiar, atau periode 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. Hanya publikasikan jika AccountProfile milik orang dewasa.

Sinkronisasi lintas perangkat

Tanda SyncAcrossDevices

Flag ini mengontrol apakah data ContinuationCluster pengguna disinkronkan di seluruh perangkat mereka (TV, ponsel, tablet, dll.). Secara default, nilainya adalah salah (false), yang berarti sinkronisasi lintas perangkat dinonaktifkan secara default.

Nilai:

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

Mendapatkan Izin:

Aplikasi media harus memberikan setelan yang jelas untuk mengaktifkan/menonaktifkan sinkronisasi lintas perangkat. Jelaskan manfaatnya kepada pengguna dan simpan preferensi pengguna sekali dan terapkan di publishContinuationCluster sebagaimana mestinya.

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

Untuk memaksimalkan fitur lintas perangkat kami, pastikan aplikasi Anda mendapatkan izin pengguna dan mengaktifkan SyncAcrossDevices ke benar. Hal ini memungkinkan konten disinkronkan secara lancar di seluruh perangkat, sehingga menghasilkan pengalaman pengguna yang lebih baik dan meningkatkan interaksi. Misalnya, partner yang menerapkannya mengalami peningkatan klik "lanjutkan menonton" sebesar 40% karena kontennya ditampilkan di beberapa perangkat.

Menghapus data Penemuan video

Untuk menghapus data pengguna secara manual dari server Google TV sebelum periode retensi standar 60 hari, 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(
  new DeleteClustersRequest.Builder()
        .setAccountProfile(AccountProfile())
        .setReason(DeleteReason.DELETE_REASON_USER_LOG_OUT)
        .setSyncAcrossDevices(true)
        .build()
)

Pengujian

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

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

Pastikan Engage Service Flag TIDAK disetel ke produksi dalam 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 ada).
- 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 publishContinuationClusters API dan data ditampilkan dengan benar di aplikasi verifikasi.
Aplikasi verifikasi akan menampilkan tanda centang "All Good" berwarna hijau untuk entity yang diterapkan dengan benar.

Gambar 1. Verifikasi Academy for App Success
Aplikasi verifikasi akan menandai entitas yang bermasalah.

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

Gambar 3. Detail Error Aplikasi Verifikasi

Panduan integrasi Engage SDK untuk TV Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Langkah 1: Persiapan

Ponsel

TV

Ponsel

TV

Integrasi

AccountProfile

Membuat entity

MovieEntity

TvEpisodeEntity

VideoClipEntity

LiveStreamingVideoEntity

Menyediakan data cluster Lanjutan

Sinkronisasi lintas perangkat

Mendapatkan Izin:

Menghapus data Penemuan video

Pengujian

Panduan integrasi Engage SDK untuk TV
Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.