Engage SDK Tontonan: Petunjuk integrasi teknis pihak ketiga

Google membuat platform di perangkat yang mengatur aplikasi pengguna menurut kategori dan memungkinkan pengalaman imersif baru untuk konsumsi dan penemuan konten aplikasi yang dipersonalisasi. Pengalaman layar penuh ini memberi partner developer peluang untuk menampilkan konten lengkap terbaik di saluran khusus di luar aplikasi mereka.

Panduan ini berisi petunjuk bagi partner developer untuk mengintegrasikan konten video mereka, menggunakan Engage SDK untuk mengisi area platform baru ini dan platform Google yang ada.

Detail integrasi

Terminologi

Integrasi ini mencakup tiga jenis cluster berikut: Rekomendasi, Lanjutan, dan Unggulan.

• Cluster Rekomendasi menampilkan saran yang dipersonalisasi untuk konten yang dapat ditonton dari setiap partner developer.

  Rekomendasi Anda menggunakan struktur berikut:

  • Cluster Rekomendasi: Tampilan UI yang berisi kelompok rekomendasi dari partner developer yang sama.

    

    Gambar 1. UI Entertainment Space menampilkan Cluster Rekomendasi dari satu partner.

  • Entity: Objek yang mewakili satu item dalam cluster. Entity dapat berupa film, acara TV, serial TV, video live, dan lainnya. Baca bagian Memberikan data entity untuk mengetahui daftar jenis entity yang didukung.

    

    Gambar 2. UI Entertainment Space menampilkan satu Entity dalam Cluster Rekomendasi milik satu partner.

• Cluster Lanjutan menampilkan video yang belum selesai dan episode relevan yang baru dirilis dari beberapa partner developer dalam satu pengelompokan UI. Setiap partner developer akan diizinkan untuk menyiarkan maksimum 10 entity di cluster Lanjutan. Penelitian telah menunjukkan bahwa rekomendasi dan konten Lanjutan yang dipersonalisasi akan menghasilkan engagement pengguna terbaik.

  

  Gambar 3. UI Entertainment Space menampilkan cluster Lanjutan dengan rekomendasi yang belum selesai dari beberapa partner (hanya satu rekomendasi yang saat ini terlihat).

• Cluster Unggulan menampilkan pilihan entity dari beberapa partner developer dalam satu pengelompokan UI. Akan ada satu cluster Unggulan yang ditampilkan di dekat bagian atas UI dengan penempatan prioritas di atas semua cluster Rekomendasi. Setiap partner developer akan diizinkan untuk menyiarkan hingga 10 entity di cluster Unggulan.

  

  Gambar 4. UI Entertainment Space menampilkan cluster Unggulan dengan rekomendasi dari beberapa partner (hanya satu rekomendasi yang saat ini terlihat).

Persiapan

Level API minimum: 19

Tambahkan library com.google.android.engage:engage-core ke aplikasi Anda:

dependencies {
    // Make sure you also include that repository in your project's build.gradle file.
    implementation 'com.google.android.engage:engage-core:1.5.2'
}

Untuk informasi selengkapnya, lihat Visibilitas paket di Android 11.

Ringkasan

Desain ini didasarkan pada implementasi layanan terikat.

Data yang dapat dipublikasikan klien tunduk pada batas berikut untuk berbagai jenis cluster:

Jenis cluster	Batas cluster	Batas maksimum entity dalam cluster
Cluster Rekomendasi	Maksimal 5	Maksimal 50
Cluster Lanjutan	Maksimal 1	Maksimal 10
Cluster Unggulan	Maksimal 1	Maksimal 10

Penting: Engage SDK telah menggantikan Media Home, yang kini tidak digunakan lagi. Jika Anda sudah memiliki integrasi Media Home yang sudah ada, ikuti petunjuk di Langkah 0 untuk memigrasikan konten Anda ke Engage SDK, yang memungkinkan konten Anda dipublikasikan ke lebih banyak perangkat dan faktor bentuk. Hubungi [e-mail]. Jika Anda tidak memiliki integrasi Media Home yang sudah ada, lanjutkan ke Langkah 1.

Langkah 0: Migrasi dari integrasi Media Home SDK yang ada

Memetakan model data dari integrasi yang ada

Jika Anda bermigrasi dari integrasi Media Home yang sudah ada, tabel berikut menguraikan cara memetakan model data di SDK yang ada ke Engage SDK baru:

Setara dengan integrasi MediaHomeVideoContract	Setara dengan integrasi Engage SDK
com.google.android.mediahome.video.PreviewChannel	com.google.android.engage.common.datamodel.RecommendationCluster
com.google.android.mediahome.video.PreviewChannel.Builder	com.google.android.engage.common.datamodel.RecommendationCluster.Builder
com.google.android.mediahome.video.PreviewChannelHelper	com.google.android.engage.video.service.AppEngageVideoClient
com.google.android.mediahome.video.PreviewProgram	Dibagi menjadi class terpisah: EventVideo, LiveStreamingVideo, Movie, TvEpisode, TvSeason, TvShow, VideoClipEntity
com.google.android.mediahome.video.PreviewProgram.Builder	Dibagi menjadi builder dalam class terpisah: EventVideo, LiveStreamingVideo, Movie, TvEpisode, TvSeason, TvShow, VideoClipEntity
com.google.android.mediahome.video.VideoContract	Sudah tidak dibutuhkan.
com.google.android.mediahome.video.WatchNextProgram	Dibagi menjadi atribut dalam class terpisah: EventVideoEntity, LiveStreamingVideoEntity, MovieEntity, TvEpisodeEntity, TvSeasonEntity, TvShowEntity, VideoClipEntity
com.google.android.mediahome.video.WatchNextProgram.Builder	Dibagi menjadi atribut dalam class terpisah: EventVideoEntity, LiveStreamingVideoEntity, MovieEntity, TvEpisodeEntity, TvSeasonEntity, TvShowEntity, VideoClipEntity

Memublikasikan cluster di Media Home SDK dibandingkan di Engage SDK

Dengan Media Home SDK, cluster dan entity dipublikasikan melalui API terpisah:

// 1. Fetch existing channels
List<PreviewChannel> channels = PreviewChannelHelper.getAllChannels();

// 2. If there are no channels, publish new channels
long channelId = PreviewChannelHelper.publishChannel(builder.build());

// 3. If there are existing channels, decide whether to update channel contents
PreviewChannelHelper.updatePreviewChannel(channelId, builder.build());

// 4. Delete all programs in the channel
PreviewChannelHelper.deleteAllPreviewProgramsByChannelId(channelId);

// 5. publish new programs in the channel
PreviewChannelHelper.publishPreviewProgram(builder.build());

Dengan Engage SDK, publikasi cluster dan entity digabungkan menjadi satu panggilan API. Semua entity dalam satu cluster dipublikasikan bersama cluster tersebut:

Kotlin

RecommendationCluster.Builder()
            .addEntity(MOVIE_ENTITY)
            .addEntity(MOVIE_ENTITY)
            .addEntity(MOVIE_ENTITY)
            .setTitle("Top Picks For You")
            .build()

Java

new RecommendationCluster.Builder()
                        .addEntity(MOVIE_ENTITY)
                        .addEntity(MOVIE_ENTITY)
                        .addEntity(MOVIE_ENTITY)
                        .setTitle("Top Picks For You")
                        .build();

Langkah 1: Memberikan data entity

SDK telah menentukan entity yang berbeda untuk mewakili setiap jenis item. Kami mendukung entity berikut untuk kategori Tontonan:

1. MovieEntity
2. TvShowEntity
3. TvSeasonEntity
4. TvEpisodeEntity
5. LiveStreamingVideoEntity
6. VideoClipEntity

Diagram berikut menguraikan atribut dan persyaratan untuk setiap jenis.

MovieEntity

Atribut	Persyaratan	Catatan
Nama	Wajib
Gambar poster	Wajib	Setidaknya harus ada satu gambar dan harus diberikan dengan rasio aspek. (Lanskap disarankan, tetapi sebaiknya teruskan gambar potret atau lanskap untuk skenario yang berbeda.) Lihat Spesifikasi Gambar untuk panduan.
URI Pemutaran	Wajib	Deep link ke aplikasi penyedia untuk mulai memutar film. Catatan: Anda dapat menggunakan deep link untuk atribusi. Lihat FAQ ini
URI halaman info	Opsional	Deep link ke aplikasi penyedia untuk menampilkan detail film. Catatan: Anda dapat menggunakan deep link untuk atribusi. Lihat FAQ ini
Tanggal rilis	Wajib	Dalam epoch milidetik.
Ketersediaan	Wajib	AVAILABLE: Konten tersedia untuk pengguna tanpa tindakan lebih lanjut. FREE_WITH_SUBSCRIPTION: Konten akan tersedia setelah pengguna membeli langganan. PAID_CONTENT: Konten harus dibeli atau disewa oleh pengguna. PURCHASED: Konten telah dibeli atau disewa oleh pengguna.
Harga penawaran	Opsional	Teks bebas
Durasi	Wajib	Dalam milidetik.
Genre	Wajib	Teks bebas
Rating konten	Wajib	Teks bebas, ikuti standar industri. (Contoh)
Jenis tonton berikutnya	Wajib bersyarat	Harus diberikan jika item berada dalam cluster Lanjutan dan harus merupakan salah satu dari empat jenis berikut: CONTINUE: Pengguna telah menonton konten ini selama lebih dari 1 menit. NEW: Pengguna telah menonton semua episode yang tersedia dari beberapa konten berepisode, tetapi episode baru telah tersedia dan hanya ada satu episode yang belum ditonton. Ini berlaku untuk acara TV, rekaman pertandingan sepak bola dalam serial, dan sebagainya. NEXT: Pengguna telah menonton satu atau beberapa episode lengkap dari beberapa konten berepisode, tetapi masih ada lebih dari satu episode yang tersisa atau satu episode tersisa dengan episode terakhir bukan "NEW" dan dirilis sebelum pengguna mulai menonton konten berepisode. WATCHLIST: Pengguna secara eksplisit memilih untuk menambahkan film, acara, atau serial ke daftar tontonan untuk memilih secara manual konten yang ingin mereka tonton berikutnya.
Waktu engagement terakhir	Wajib bersyarat	Harus diberikan saat item berada dalam cluster Lanjutan. Dalam epoch milidetik.
Waktu posisi pemutaran terakhir	Wajib bersyarat	Harus diberikan saat item berada dalam cluster Lanjutan dan WatchNextType adalah CONTINUE. Dalam epoch milidetik.

TvShowEntity

Atribut	Persyaratan	Catatan
Nama	Wajib
Gambar poster	Wajib	Setidaknya harus ada satu gambar dan harus diberikan dengan rasio aspek. (Lanskap disarankan, tetapi sebaiknya teruskan gambar potret atau lanskap untuk skenario yang berbeda.) Lihat Spesifikasi Gambar untuk panduan.
URI halaman info	Wajib	Deep link ke aplikasi penyedia untuk menampilkan detail acara TV. Catatan: Anda dapat menggunakan deep link untuk atribusi. Lihat FAQ ini
URI Pemutaran	Opsional	Deep link ke aplikasi penyedia untuk mulai memutar acara TV. Catatan: Anda dapat menggunakan deep link untuk atribusi. Lihat FAQ ini
Tanggal disiarkan episode pertama	Wajib	Dalam epoch milidetik.
Tanggal disiarkan episode terbaru	Opsional	Dalam epoch milidetik.
Ketersediaan	Wajib	AVAILABLE: Konten tersedia untuk pengguna tanpa tindakan lebih lanjut. FREE_WITH_SUBSCRIPTION: Konten akan tersedia setelah pengguna membeli langganan. PAID_CONTENT: Konten harus dibeli atau disewa oleh pengguna. PURCHASED: Konten telah dibeli atau disewa oleh pengguna.
Harga penawaran	Opsional	Teks bebas
Jumlah season	Wajib	Bilangan bulat positif
Genre	Wajib	Teks bebas
Rating konten	Wajib	Teks bebas, ikuti standar industri. (Contoh)
Jenis tonton berikutnya	Wajib bersyarat	Harus diberikan jika item berada dalam cluster Lanjutan dan harus merupakan salah satu dari empat jenis berikut: CONTINUE: Pengguna telah menonton konten ini selama lebih dari 1 menit. NEW: Pengguna telah menonton semua episode yang tersedia dari beberapa konten berepisode, tetapi episode baru telah tersedia dan hanya ada satu episode yang belum ditonton. Ini berlaku untuk acara TV, rekaman pertandingan sepak bola dalam serial, dan sebagainya. NEXT: Pengguna telah menonton satu atau beberapa episode lengkap dari beberapa konten berepisode, tetapi masih ada lebih dari satu episode yang tersisa atau satu episode tersisa dengan episode terakhir bukan "NEW" dan dirilis sebelum pengguna mulai menonton konten berepisode. WATCHLIST: Pengguna secara eksplisit memilih untuk menambahkan film, acara, atau serial ke daftar tontonan untuk memilih secara manual konten yang ingin mereka tonton berikutnya.
Waktu engagement terakhir	Wajib bersyarat	Harus diberikan saat item berada dalam cluster Lanjutan. Dalam epoch milidetik.
Waktu posisi pemutaran terakhir	Wajib bersyarat	Harus diberikan saat item berada dalam cluster Lanjutan dan WatchNextType adalah CONTINUE. Dalam epoch milidetik.

TvSeasonEntity

Atribut	Persyaratan	Catatan
Nama	Wajib
Gambar poster	Wajib	Setidaknya harus ada satu gambar dan harus diberikan dengan rasio aspek. (Lanskap disarankan, tetapi sebaiknya teruskan gambar potret atau lanskap untuk skenario yang berbeda.) Lihat Spesifikasi Gambar untuk panduan.
URI halaman info	Wajib	Deep link ke aplikasi penyedia untuk menampilkan detail season acara TV. Catatan: Anda dapat menggunakan deep link untuk atribusi. Lihat FAQ ini
URI Pemutaran	Opsional	Deep link ke aplikasi penyedia untuk mulai memutar season acara TV. Catatan: Anda dapat menggunakan deep link untuk atribusi. Lihat FAQ ini
Menampilkan nomor Season	Opsional Tersedia di v1.3.1	String
Tanggal disiarkan episode pertama	Wajib	Dalam epoch milidetik.
Tanggal disiarkan episode terbaru	Opsional	Dalam epoch milidetik.
Ketersediaan	Wajib	AVAILABLE: Konten tersedia untuk pengguna tanpa tindakan lebih lanjut. FREE_WITH_SUBSCRIPTION: Konten akan tersedia setelah pengguna membeli langganan. PAID_CONTENT: Konten harus dibeli atau disewa oleh pengguna. PURCHASED: Konten telah dibeli atau disewa oleh pengguna.
Harga penawaran	Opsional	Teks bebas
Jumlah episode	Wajib	Bilangan bulat positif
Genre	Wajib	Teks bebas
Rating konten	Wajib	Teks bebas, ikuti standar industri. (Contoh)
Jenis tonton berikutnya	Wajib bersyarat	Harus diberikan jika item berada dalam cluster Lanjutan dan harus merupakan salah satu dari empat jenis berikut: CONTINUE: Pengguna telah menonton konten ini selama lebih dari 1 menit. NEW: Pengguna telah menonton semua episode yang tersedia dari beberapa konten berepisode, tetapi episode baru telah tersedia dan hanya ada satu episode yang belum ditonton. Ini berlaku untuk acara TV, rekaman pertandingan sepak bola dalam serial, dan sebagainya. NEXT: Pengguna telah menonton satu atau beberapa episode lengkap dari beberapa konten berepisode, tetapi masih ada lebih dari satu episode yang tersisa atau satu episode tersisa dengan episode terakhir bukan "NEW" dan dirilis sebelum pengguna mulai menonton konten berepisode. WATCHLIST: Pengguna secara eksplisit memilih untuk menambahkan film, acara, atau serial ke daftar tontonan untuk memilih secara manual konten yang ingin mereka tonton berikutnya.
Waktu engagement terakhir	Wajib bersyarat	Harus diberikan saat item berada dalam cluster Lanjutan. Dalam epoch milidetik.
Waktu posisi pemutaran terakhir	Wajib bersyarat	Harus diberikan saat item berada dalam cluster Lanjutan dan WatchNextType adalah CONTINUE. Dalam epoch milidetik.

TvEpisodeEntity

Atribut	Persyaratan	Catatan
Nama	Wajib
Gambar poster	Wajib	Setidaknya harus ada satu gambar dan harus diberikan dengan rasio aspek. (Lanskap disarankan, tetapi sebaiknya teruskan gambar potret atau lanskap untuk skenario yang berbeda.) Lihat Spesifikasi Gambar untuk panduan.
URI Pemutaran	Wajib	Deep link ke aplikasi penyedia untuk mulai memutar episode. Catatan: Anda dapat menggunakan deep link untuk atribusi. Lihat FAQ ini
URI halaman info	Opsional	Deep link ke aplikasi penyedia untuk menampilkan detail tentang episode acara TV. Catatan: Anda dapat menggunakan deep link untuk atribusi. Lihat FAQ ini
Menampilkan nomor Episode	Opsional Tersedia di v1.3.1	String
Tanggal disiarkan	Wajib	Dalam epoch milidetik.
Ketersediaan	Wajib	AVAILABLE: Konten tersedia untuk pengguna tanpa tindakan lebih lanjut. FREE_WITH_SUBSCRIPTION: Konten akan tersedia setelah pengguna membeli langganan. PAID_CONTENT: Konten harus dibeli atau disewa oleh pengguna. PURCHASED: Konten telah dibeli atau disewa oleh pengguna.
Harga penawaran	Opsional	Teks bebas
Durasi	Wajib	Harus berupa nilai positif dalam milidetik.
Genre	Wajib	Teks bebas
Rating konten	Wajib	Teks bebas, ikuti standar industri. (Contoh)
Jenis tonton berikutnya	Wajib bersyarat	Harus diberikan jika item berada dalam cluster Lanjutan dan harus merupakan salah satu dari empat jenis berikut: CONTINUE: Pengguna telah menonton konten ini selama lebih dari 1 menit. NEW: Pengguna telah menonton semua episode yang tersedia dari beberapa konten berepisode, tetapi episode baru telah tersedia dan hanya ada satu episode yang belum ditonton. Ini berlaku untuk acara TV, rekaman pertandingan sepak bola dalam serial, dan sebagainya. NEXT: Pengguna telah menonton satu atau beberapa episode lengkap dari beberapa konten berepisode, tetapi masih ada lebih dari satu episode yang tersisa atau satu episode tersisa dengan episode terakhir bukan "NEW" dan dirilis sebelum pengguna mulai menonton konten berepisode. WATCHLIST: Pengguna secara eksplisit memilih untuk menambahkan film, acara, atau serial ke daftar tontonan untuk memilih secara manual konten yang ingin mereka tonton berikutnya.
Waktu engagement terakhir	Wajib bersyarat	Harus diberikan saat item berada dalam cluster Lanjutan. Dalam epoch milidetik.
Waktu posisi pemutaran terakhir	Wajib bersyarat	Harus diberikan saat item berada dalam cluster Lanjutan dan WatchNextType adalah CONTINUE. Dalam epoch milidetik.

LiveStreamingVideoEntity

Atribut	Persyaratan	Catatan
Nama	Wajib
Gambar poster	Wajib	Setidaknya harus ada satu gambar dan harus diberikan dengan rasio aspek. (Lanskap disarankan, tetapi sebaiknya teruskan gambar potret atau lanskap untuk skenario yang berbeda.) Lihat Spesifikasi Gambar untuk panduan.
URI Pemutaran	Wajib	Deep link ke aplikasi penyedia untuk mulai memutar video. Catatan: Anda dapat menggunakan deep link untuk atribusi. Lihat FAQ ini
Penyiar	Wajib	Teks bebas
Waktu mulai	Opsional	Dalam epoch milidetik.
Waktu akhir	Opsional	Dalam epoch milidetik.
Jumlah tayangan	Opsional	Teks bebas, harus dilokalkan.
Jenis tonton berikutnya	Wajib bersyarat	Harus diberikan jika item berada dalam cluster Lanjutan dan harus merupakan salah satu dari empat jenis berikut: CONTINUE: Pengguna telah menonton konten ini selama lebih dari 1 menit. NEW: Pengguna telah menonton semua episode yang tersedia dari beberapa konten berepisode, tetapi episode baru telah tersedia dan hanya ada satu episode yang belum ditonton. Ini berlaku untuk acara TV, rekaman pertandingan sepak bola dalam serial, dan sebagainya. NEXT: Pengguna telah menonton satu atau beberapa episode lengkap dari beberapa konten berepisode, tetapi masih ada lebih dari satu episode yang tersisa atau satu episode tersisa dengan episode terakhir bukan "NEW" dan dirilis sebelum pengguna mulai menonton konten berepisode. WATCHLIST: Pengguna secara eksplisit memilih untuk menambahkan film, acara, atau serial ke daftar tontonan untuk memilih secara manual konten yang ingin mereka tonton berikutnya.
Waktu engagement terakhir	Wajib bersyarat	Harus diberikan saat item berada dalam cluster Lanjutan. Dalam epoch milidetik.
Waktu posisi pemutaran terakhir	Wajib bersyarat	Harus diberikan saat item berada dalam cluster Lanjutan dan WatchNextType adalah CONTINUE. Dalam epoch milidetik.

VideoClipEntity

Objek VideoClipEntity mewakili entity video yang berasal dari media sosial, seperti TikTok atau YouTube.

Atribut	Persyaratan	Catatan
Nama	Wajib
Gambar poster	Wajib	Setidaknya harus ada satu gambar dan harus diberikan dengan rasio aspek. (Lanskap disarankan, tetapi sebaiknya teruskan gambar potret atau lanskap untuk skenario yang berbeda.) Lihat Spesifikasi Gambar untuk panduan.
URI Pemutaran	Wajib	Deep link ke aplikasi penyedia untuk mulai memutar video. Catatan: Anda dapat menggunakan deep link untuk atribusi. Lihat FAQ ini
Waktu pembuatan	Wajib	Dalam epoch milidetik.
Durasi	Wajib	Harus berupa nilai positif dalam milidetik.
Kreator	Wajib	Teks bebas
Gambar Kreator	Opsional	Gambar avatar Kreator
Jumlah tayangan	Opsional	Teks bebas, harus dilokalkan.
Jenis tonton berikutnya	Wajib bersyarat	Harus diberikan jika item berada dalam cluster Lanjutan dan harus merupakan salah satu dari empat jenis berikut: CONTINUE: Pengguna telah menonton konten ini selama lebih dari 1 menit. NEW: Pengguna telah menonton semua episode yang tersedia dari beberapa konten berepisode, tetapi episode baru telah tersedia dan hanya ada satu episode yang belum ditonton. Ini berlaku untuk acara TV, rekaman pertandingan sepak bola dalam serial, dan sebagainya. NEXT: Pengguna telah menonton satu atau beberapa episode lengkap dari beberapa konten berepisode, tetapi masih ada lebih dari satu episode yang tersisa atau satu episode tersisa dengan episode terakhir bukan "NEW" dan dirilis sebelum pengguna mulai menonton konten berepisode. WATCHLIST: Pengguna secara eksplisit memilih untuk menambahkan film, acara, atau serial ke daftar tontonan untuk memilih secara manual konten yang ingin mereka tonton berikutnya.
Waktu engagement terakhir	Wajib bersyarat	Harus diberikan saat item berada dalam cluster Lanjutan. Dalam epoch milidetik.
Waktu posisi pemutaran terakhir	Wajib bersyarat	Harus diberikan saat item berada dalam cluster Lanjutan dan WatchNextType adalah CONTINUE. Dalam epoch milidetik.

Spesifikasi gambar

Bagian berikut mencantumkan spesifikasi yang diperlukan untuk aset gambar:

Format file

PNG, JPG, GIF statis, WebP

Ukuran file maksimum

5120 KB

Rekomendasi tambahan

• Area aman gambar: Tempatkan konten penting Anda di 80% bagian tengah gambar.

Contoh

Kotlin

var movie = MovieEntity.Builder()
    .setName("Avengers")
    .addPosterImage(Image.Builder()
                          .setImageUri(Uri.parse("http://www.x.com/image.png"))
                          .setImageHeightInPixel(960)
                          .setImageWidthInPixel(408)
                          .build())
    .setPlayBackUri(Uri.parse("http://tv.com/playback/1"))
    .setReleaseDateEpochMillis(1633032895L)
    .setAvailability(ContentAvailability.AVAILABILITY_AVAILABLE)
    .setDurationMillis(12345678L)
    .addGenre("action")
    .addContentRating("R")
    .setWatchNextType(WatchNextType.TYPE_NEW)
    .setLastEngagementTimeMillis(1664568895L)
    .build()

Java

MovieEntity movie = new MovieEntity.Builder()
                  .setName("Avengers")
                  .addPosterImage(
                      new Image.Builder()
                          .setImageUri(Uri.parse("http://www.x.com/image.png"))
                          .setImageHeightInPixel(960)
                          .setImageWidthInPixel(408)
                          .build())
                  .setPlayBackUri(Uri.parse("http://tv.com/playback/1"))
                  .setReleaseDateEpochMillis(1633032895L)
                  .setAvailability(ContentAvailability.AVAILABILITY_AVAILABLE)
                  .setDurationMillis(12345678L)
                  .addGenre("action")
                  .addContentRating("R")
                  .setWatchNextType(WatchNextType.TYPE_NEW)
                  .setLastEngagementTimeMillis(1664568895L)
                  .build();

Langkah 2: Menyediakan data Cluster

Sebaiknya jalankan tugas publikasi konten di latar belakang (misalnya, menggunakan WorkManager) dan dijadwalkan secara berkala atau berbasis peristiwa (misalnya, setiap kali pengguna membuka aplikasi atau saat pengguna menambahkan sesuatu ke keranjangnya).

AppEngagePublishClient bertanggung jawab untuk memublikasikan cluster. API berikut tersedia di klien:

• isServiceAvailable
• publishRecommendationClusters
• publishFeaturedCluster
• publishContinuationCluster
• publishUserAccountManagementRequest
• updatePublishStatus
• deleteRecommendationsClusters
• deleteFeaturedCluster
• deleteContinuationCluster
• deleteUserManagementCluster
• deleteClusters

isServiceAvailable

API ini digunakan untuk memeriksa apakah layanan tersedia untuk integrasi, dan apakah konten dapat ditampilkan di perangkat atau tidak.

Kotlin

client.isServiceAvailable.addOnCompleteListener { task ->
    if (task.isSuccessful) {
        // Handle IPC call success
        if(task.result) {
          // Service is available on the device, proceed with content publish
          // calls.
        } else {
          // Service is not available, no further action is needed.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
}

Java

client.isServiceAvailable().addOnCompleteListener(task - > {
    if (task.isSuccessful()) {
        // Handle success
        if(task.getResult()) {
          // Service is available on the device, proceed with content publish
          // calls.
        } else {
          // Service is not available, no further action is needed.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
});

Catatan: Sebaiknya jalankan tugas berkala untuk memeriksa apakah layanan tersedia di lain waktu. Ketersediaan layanan dapat berubah dengan upgrade versi Android, upgrade aplikasi, penginstalan, dan uninstal. Dengan memastikan pemeriksaan tugas berkala pada interval waktu tertentu, data dapat dipublikasikan setelah layanan tersedia.

publishRecommendationClusters

API ini digunakan untuk memublikasikan daftar objek RecommendationCluster.

Penting: API publikasi adalah API penyisipan yang menggantikan konten yang sudah ada. Jangan memanggil API penghapusan dan publikasi secara berurutan untuk mengganti konten karena API publikasi melakukannya secara inheren.

Kotlin

client.publishRecommendationClusters(
      PublishRecommendationClustersRequest.Builder()
        .addRecommendationCluster(
          RecommendationCluster.Builder()
            .addEntity(entity1)
            .addEntity(entity2)
            .setTitle("Top Picks For You")
            .build()
        )
        .build()
    )

Java

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Top Picks For You")
                        .build())
                .build());

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

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

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

publishFeaturedCluster

API ini digunakan untuk memublikasikan daftar objek FeaturedCluster.

Penting: API publikasi adalah API penyisipan yang menggantikan konten yang sudah ada. Jangan memanggil API penghapusan dan publikasi secara berurutan untuk mengganti konten karena API publikasi melakukannya secara inheren.

Kotlin

client.publishFeaturedCluster(
    PublishFeaturedClusterRequest.Builder()
      .setFeaturedCluster(
        FeaturedCluster.Builder()
          .addEntity(entity1)
          .addEntity(entity2)
          .build())
      .build())

Java

client.publishFeaturedCluster(
            new PublishFeaturedClustersRequest.Builder()
                .addFeaturedCluster(
                    new FeaturedCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build());

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

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

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

publishContinuationCluster

API ini digunakan untuk memublikasikan objek ContinuationCluster.

Penting: API publikasi adalah API penyisipan yang menggantikan konten yang sudah ada. Jangan memanggil API penghapusan dan publikasi secara berurutan untuk mengganti konten karena API publikasi melakukannya secara inheren.

Kotlin

client.publishContinuationCluster(
    PublishContinuationClusterRequest.Builder()
      .setContinuationCluster(
        ContinuationCluster.Builder()
          .addEntity(entity1)
          .addEntity(entity2)
          .build())
      .build())

Java

client.publishContinuationCluster(
            new PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    new ContinuationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .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 Cluster Lanjutan yang diperbarui.

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

publishUserAccountManagementRequest

API ini digunakan untuk memublikasikan kartu Login. Tindakan login mengarahkan pengguna ke halaman login aplikasi sehingga aplikasi dapat memublikasikan konten (atau memberikan konten yang lebih dipersonalisasi)

Metadata berikut adalah bagian dari Kartu Login -

Atribut	Persyaratan	Deskripsi
URI Tindakan	Wajib	Deeplink ke Tindakan (yaitu membuka halaman login aplikasi)
Gambar	Opsional - Jika tidak diberikan, Judul harus diberikan	Gambar Ditampilkan pada Kartu Gambar rasio aspek 16x9 dengan resolusi 1264x712
Judul	Opsional - Jika tidak diberikan, Gambar harus diberikan	Judul pada Kartu
Teks Tindakan	Opsional	Teks yang Ditampilkan pada CTA (yaitu Login)
Subjudul	Opsional	Subjudul Opsional pada Kartu

Penting: API publikasi adalah API penyisipan yang menggantikan konten yang sudah ada. Jangan memanggil API penghapusan dan publikasi secara berurutan untuk mengganti konten karena API publikasi melakukannya secara inheren.

Kotlin

var SIGN_IN_CARD_ENTITY =
      SignInCardEntity.Builder()
          .addPosterImage(
              Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(500)
                  .setImageWidthInPixel(500)
                  .build())
          .setActionText("Sign In")
          .setActionUri(Uri.parse("http://xx.com/signin"))
          .build()

client.publishUserAccountManagementRequest(
            PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

Java

SignInCardEntity SIGN_IN_CARD_ENTITY =
      new SignInCardEntity.Builder()
          .addPosterImage(
              new Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(500)
                  .setImageWidthInPixel(500)
                  .build())
          .setActionText("Sign In")
          .setActionUri(Uri.parse("http://xx.com/signin"))
          .build();

client.publishUserAccountManagementRequest(
            new PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

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

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

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

updatePublishStatus

Jika untuk alasan bisnis internal apa pun, tidak ada cluster yang dipublikasikan, sebaiknya perbarui status publikasi menggunakan API updatePublishStatus. Hal ini penting karena:

• Memberikan status dalam semua skenario, bahkan saat konten dipublikasikan (STATUS == PUBLISHED), sangat penting untuk mengisi dasbor yang menggunakan status eksplisit ini untuk menyampaikan kondisi dan metrik integrasi Anda yang lain.
• Jika tidak ada konten yang dipublikasikan, tetapi status integrasi tidak rusak (STATUS == NOT_PUBLISHED), Google dapat menghindari pemicuan pemberitahuan di dasbor kondisi aplikasi. Fitur ini mengonfirmasi bahwa konten tidak dipublikasikan karena situasi yang diharapkan dari sudut pandang penyedia.
• Hal ini membantu developer memberikan insight tentang kapan data dipublikasikan atau tidak.
• Google dapat menggunakan kode status untuk mendorong pengguna melakukan tindakan tertentu dalam aplikasi sehingga mereka dapat melihat konten aplikasi atau mengatasinya.

Daftar kode status publikasi yang memenuhi syarat adalah:

// Content is published
AppEngagePublishStatusCode.PUBLISHED,

// Content is not published as user is not signed in
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN,

// Content is not published as user is not subscribed
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SUBSCRIPTION,

// Content is not published as user location is ineligible
AppEngagePublishStatusCode.NOT_PUBLISHED_INELIGIBLE_LOCATION,

// Content is not published as there is no eligible content
AppEngagePublishStatusCode.NOT_PUBLISHED_NO_ELIGIBLE_CONTENT,

// Content is not published as the feature is disabled by the client
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_FEATURE_DISABLED_BY_CLIENT,

// Content is not published as the feature due to a client error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_CLIENT_ERROR,

// Content is not published as the feature due to a service error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_SERVICE_ERROR,

// Content is not published due to some other reason
// Reach out to engage-developers@ before using this enum.
AppEngagePublishStatusCode.NOT_PUBLISHED_OTHER

Jika konten tidak dipublikasikan karena pengguna tidak login, Google merekomendasikan untuk memublikasikan Kartu Login. Jika karena alasan apa pun penyedia tidak dapat memublikasikan Kartu Login, sebaiknya panggil API updatePublishStatus dengan kode status NOT_PUBLISHED_REQUIRES_SIGN_IN

Kotlin

client.updatePublishStatus(
   PublishStatusRequest.Builder()
     .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
     .build())

Java

client.updatePublishStatus(
    new PublishStatusRequest.Builder()
        .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
        .build());

deleteRecommendationClusters

API ini digunakan untuk menghapus konten Cluster Rekomendasi.

Penting: API penghapusan hanya boleh dipanggil jika tidak ada konten untuk dipublikasikan. Jangan memanggil API penghapusan dan publikasi secara berurutan untuk mengganti konten karena API publikasi melakukannya secara inheren. Hubungi engage-developers@ sebelum menggunakan API penghapusan.

Kotlin

client.deleteRecommendationClusters()

Java

client.deleteRecommendationClusters();

Saat menerima permintaan, layanan akan menghapus data yang ada dari Cluster Rekomendasi. Jika terjadi error, seluruh permintaan akan ditolak dan status yang ada dipertahankan.

Catatan: API ini tersedia mulai versi 1.1.0 dan seterusnya.

deleteFeaturedCluster

API ini digunakan untuk menghapus konten Cluster Unggulan.

Penting: API penghapusan hanya boleh dipanggil jika tidak ada konten untuk dipublikasikan. Jangan memanggil API penghapusan dan publikasi secara berurutan untuk mengganti konten karena API publikasi melakukannya secara inheren. Hubungi engage-developers@ sebelum menggunakan API penghapusan.

Kotlin

client.deleteFeaturedCluster()

Java

client.deleteFeaturedCluster();

Saat menerima permintaan, layanan akan menghapus data yang ada dari Cluster Unggulan. Jika terjadi error, seluruh permintaan akan ditolak dan status yang ada dipertahankan.

Catatan: API ini tersedia mulai versi 1.1.0 dan seterusnya.

deleteContinuationCluster

API ini digunakan untuk menghapus konten Cluster Lanjutan.

Penting: API penghapusan hanya boleh dipanggil jika tidak ada konten untuk dipublikasikan. Jangan memanggil API penghapusan dan publikasi secara berurutan untuk mengganti konten karena API publikasi melakukannya secara inheren. Hubungi engage-developers@ sebelum menggunakan API penghapusan.

Kotlin

client.deleteContinuationCluster()

Java

client.deleteContinuationCluster();

Saat menerima permintaan, layanan akan menghapus data yang ada dari Cluster Lanjutan. Jika terjadi error, seluruh permintaan akan ditolak dan status yang ada dipertahankan.

Catatan: API ini tersedia mulai versi 1.1.0 dan seterusnya.

deleteUserManagementCluster

API ini digunakan untuk menghapus konten Cluster UserAccountManagement.

Penting: API penghapusan hanya boleh dipanggil jika tidak ada konten untuk dipublikasikan. Jangan memanggil API penghapusan dan publikasi secara berurutan untuk mengganti konten karena API publikasi melakukannya secara inheren. Hubungi engage-developers@ sebelum menggunakan API penghapusan.

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

Saat menerima permintaan, layanan akan menghapus data yang ada dari Cluster UserAccountManagement. Jika terjadi error, seluruh permintaan akan ditolak dan status yang ada dipertahankan.

Catatan: API ini tersedia mulai versi 1.1.0 dan seterusnya.

deleteClusters

API ini digunakan untuk menghapus konten jenis cluster tertentu.

Penting: API penghapusan hanya boleh dipanggil jika tidak ada konten untuk dipublikasikan. Jangan memanggil API penghapusan dan publikasi secara berurutan untuk mengganti konten karena API publikasi melakukannya secara inheren. Hubungi engage-developers@ sebelum menggunakan API penghapusan.

Kotlin

client.deleteClusters(
    DeleteClustersRequest.Builder()
      .addClusterType(ClusterType.TYPE_CONTINUATION)
      .addClusterType(ClusterType.TYPE_FEATURED)
      .addClusterType(ClusterType.TYPE_RECOMMENDATION)
      .build())

Java

client.deleteClusters(
            new DeleteClustersRequest.Builder()
                .addClusterType(ClusterType.TYPE_CONTINUATION)
                .addClusterType(ClusterType.TYPE_FEATURED)
                .addClusterType(ClusterType.TYPE_RECOMMENDATION)
                .build());

Saat menerima permintaan tersebut, layanan akan menghapus data yang ada dari semua cluster yang cocok dengan jenis cluster yang ditentukan. Klien dapat memilih untuk meneruskan satu atau beberapa jenis cluster. Jika terjadi error, seluruh permintaan akan ditolak dan status yang ada dipertahankan.

Penanganan error

Sangat disarankan untuk memproses hasil tugas dari API publikasi sehingga tindakan lanjutan dapat diambil untuk memulihkan dan mengirim ulang tugas yang berhasil.

Kotlin

client.publishRecommendationClusters(
        PublishRecommendationClustersRequest.Builder()
          .addRecommendationCluster(..)
          .build())
      .addOnCompleteListener { task ->
        if (task.isSuccessful) {
          // do something
        } else {
          val exception = task.exception
          if (exception is AppEngageException) {
            @AppEngageErrorCode val errorCode = exception.errorCode
            if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) {
              // do something
            }
          }
        }
      }

Java

client.publishRecommendationClusters(
              new PublishRecommendationClustersRequest.Builder()
                  .addRecommendationCluster(...)
                  .build())
          .addOnCompleteListener(
              task -> {
                if (task.isSuccessful()) {
                  // do something
                } else {
                  Exception exception = task.getException();
                  if (exception instanceof AppEngageException) {
                    @AppEngageErrorCode
                    int errorCode = ((AppEngageException) exception).getErrorCode();
                    if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) {
                      // do something
                    }
                  }
                }
              });

Error akan ditampilkan sebagai AppEngageException dengan penyebab disertakan sebagai kode error.

Kode error	Nama error	Catatan
1	SERVICE_NOT_FOUND	Layanan tidak tersedia di perangkat yang ditentukan.
2	SERVICE_NOT_AVAILABLE	Layanan tersedia di perangkat tertentu, tetapi tidak tersedia pada saat panggilan (misalnya, dinonaktifkan secara eksplisit).
3	SERVICE_CALL_EXECUTION_FAILURE	Eksekusi tugas gagal karena masalah threading. Dalam hal ini, tindakan tersebut dapat dicoba lagi.
4	SERVICE_CALL_PERMISSION_DENIED	Pemanggil tidak diizinkan untuk melakukan panggilan layanan.
5	SERVICE_CALL_INVALID_ARGUMENT	Permintaan berisi data yang tidak valid (misalnya, lebih dari jumlah cluster yang diizinkan).
6	SERVICE_CALL_INTERNAL	Terjadi error di sisi layanan.
7	SERVICE_CALL_RESOURCE_EXHAUSTED	Panggilan layanan terlalu sering dilakukan.

Langkah 3: Menangani intent siaran

Selain melakukan panggilan API publikasi konten melalui tugas, Anda juga harus menyiapkan BroadcastReceiver untuk menerima permintaan publikasi konten.

Tujuan intent siaran terutama untuk pengaktifan kembali aplikasi dan memaksa sinkronisasi data. Intent siaran tidak didesain untuk dikirim terlalu sering. Intent itu hanya dipicu jika Layanan Engage menyimpulkan bahwa konten mungkin sudah tidak berlaku (misalnya, seminggu yang lalu). Dengan demikian, pengguna menjadi lebih yakin bahwa mereka dapat memiliki pengalaman konten baru meskipun aplikasi tidak dijalankan dalam waktu yang lama.

BroadcastReceiver harus disiapkan dengan dua cara berikut:

• Daftarkan instance class BroadcastReceiver secara dinamis menggunakan Context.registerReceiver(). Hal ini memungkinkan komunikasi dari aplikasi yang masih aktif dalam memori.

Kotlin

class AppEngageBroadcastReceiver : BroadcastReceiver(){
  // Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION broadcast
  // is received
  // Trigger featured cluster publish when PUBLISH_FEATURED broadcast is received
  // Trigger continuation cluster publish when PUBLISH_CONTINUATION broadcast is
  // received
}

fun registerBroadcastReceivers(context: Context){
  var  context = context
  context = context.applicationContext

// Register Recommendation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_RECOMMENDATION))

// Register Featured Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_FEATURED))

// Register Continuation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_CONTINUATION))
}

Java

class AppEngageBroadcastReceiver extends BroadcastReceiver {
// Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION broadcast
// is received

// Trigger featured cluster publish when PUBLISH_FEATURED broadcast is received

// Trigger continuation cluster publish when PUBLISH_CONTINUATION broadcast is
// received
}

public static void registerBroadcastReceivers(Context context) {

context = context.getApplicationContext();

// Register Recommendation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_RECOMMENDATION));

// Register Featured Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_FEATURED));

// Register Continuation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_CONTINUATION));

}

• Deklarasikan penerapan secara statis dengan tag <receiver> di file AndroidManifest.xml Anda. Hal ini memungkinkan aplikasi menerima intent siaran ketika tidak sedang berjalan, dan juga memungkinkan aplikasi untuk memublikasikan konten.

<application>
   <receiver
      android:name=".AppEngageBroadcastReceiver"
      android:exported="true"
      android:enabled="true">
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_RECOMMENDATION" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_FEATURED" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_CONTINUATION" />
      </intent-filter>
   </receiver>
</application>

Intent berikut dikirim oleh layanan:

• com.google.android.engage.action.PUBLISH_RECOMMENDATION Sebaiknya mulai panggilan publishRecommendationClusters saat menerima intent ini.
• com.google.android.engage.action.PUBLISH_FEATURED Sebaiknya mulai panggilan publishFeaturedCluster saat menerima intent ini.
• com.google.android.engage.action.PUBLISH_CONTINUATION Sebaiknya mulai panggilan publishContinuationCluster saat menerima intent ini.

Alur kerja integrasi

Untuk panduan langkah demi langkah cara memverifikasi integrasi Anda setelah selesai, lihat Alur kerja integrasi developer untuk Engage.

FAQ

Lihat Pertanyaan Umum tentang Engage SDK untuk mengetahui FAQ.

Kontak

Hubungi [e-mail] jika ada pertanyaan selama proses integrasi.

Langkah berikutnya

Setelah menyelesaikan integrasi ini, langkah-langkah Anda berikutnya adalah sebagai berikut:

• Kirim email ke [e-mail] dan lampirkan APK terintegrasi yang siap diuji oleh Google.
• Google melakukan verifikasi dan peninjauan secara internal untuk memastikan integrasi berfungsi seperti yang diharapkan. Jika diperlukan perubahan, Google akan menghubungi Anda dengan menyertakan detail yang diperlukan.
• Setelah pengujian selesai dan tidak ada perubahan yang diperlukan, Google akan menghubungi Anda untuk memberi tahu bahwa Anda dapat mulai memublikasikan APK yang diupdate dan terintegrasi ke Play Store.
• Setelah Google mengonfirmasi bahwa APK yang diupdate telah dipublikasikan ke Play Store, cluster Rekomendasi, Unggulan, dan Lanjutan dapat dipublikasikan dan terlihat oleh pengguna.