Engage SDK untuk rekomendasi video

Panduan ini berisi petunjuk bagi developer untuk mengintegrasikan konten video yang direkomendasikan, menggunakan Engage SDK, untuk mengisi pengalaman rekomendasi di seluruh platform Google, seperti TV, perangkat seluler, dan tablet.

Rekomendasi memanfaatkan Cluster rekomendasi untuk menampilkan film dan acara TV, dari beberapa aplikasi dalam satu pengelompokan UI. Setiap partner developer dapat menyiarkan maksimum 25 entity di setiap cluster rekomendasi dan dapat ada maksimum 7 cluster rekomendasi per permintaan.

Persiapan

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

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

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

    Untuk Perangkat Seluler

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

    untuk TV

    
      dependencies {
        implementation 'com.google.android.engage:engage-tv:1.0.2
      }
    
  2. Tetapkan lingkungan layanan Engage ke produksi dalam file AndroidManifest.xml.

    Untuk apk seluler

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

    Untuk apk TV

    
    <meta-data
        android:name="com.google.android.engage.service.ENV"
        android:value="PRODUCTION">
    </meta-data>
    
  3. Menjalankan publikasi di layanan latar depan.

  4. Publikasikan data Rekomendasi paling banyak sekali sehari, yang dipicu oleh salah satu dari

    1. Login pertama pengguna pada hari itu. (atau)
    2. Saat pengguna mulai berinteraksi dengan aplikasi.

Integrasi

AppEngagePublishClient memublikasikan cluster rekomendasi. Gunakan metode publishRecommendationClusters untuk memublikasikan objek rekomendasi.

Gunakan isServiceAvailable()2 untuk memeriksa apakah layanan tersedia untuk integrasi.

val client = AppEngagePublishClient(context)

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.
      client.publishRecommendationClusters(recommendationRequest)
    } else {
      // Service is not available
    }
  } else {
    // The IPC call itself fails, proceed with error handling logic here,
    // such as retry.
  }
}

Cluster rekomendasi dan permintaan publikasi

Cluster adalah pengelompokan entitas secara logis. Contoh kode berikut menjelaskan cara membuat cluster berdasarkan preferensi Anda dan cara membuat permintaan publikasi untuk semua cluster.

// cluster for popular movies
val recommendationCluster1 = RecommendationCluster
  .Builder()
  .addEntity(movie)
  .addEntity(tvShow)
  .setTitle("Popular Movies")
  .build()

// cluster for top searches
val recommendationCluster2 = RecommendationCluster
  .Builder()
  .addEntity(movie)
  .addEntity(tvShow)
  .setTitle("Top Searches")
  .build()

// creating a publishing request
val recommendationRequest = PublishRecommendationClustersRequest
  .Builder()
  .setSyncAcrossDevices(true)
  .setAccountProfile(accountProfile)
  .addRecommendationCluster(recommendationCluster1)
  .addRecommendationCluster(recommendationCluster2)
  .build()

Membuat profil akun

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

  1. 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.
  2. ID Profil (opsional): Jika aplikasi Anda mendukung beberapa profil dalam satu akun, berikan ID unik untuk profil pengguna tertentu.
  3. Lokalitas(opsional): Anda dapat memberikan bahasa pilihan pengguna secara opsional. Kolom ini berguna jika Anda mengirim MediaActionFeedEntity di RecommendationRequest.
// If app only supports account
val accountProfile = AccountProfile.Builder()
  .setAccountId("account_id")
  .build();

// If app supports both account and profile
val accountProfile = AccountProfile.Builder()
  .setAccountId("account_id")
  .setProfileId("profile_id")
  .build();

// set Locale
val accountProfile = AccountProfile.Builder()
  .setAccountId("account_id")
  .setProfileId("profile_id")
  .setLocale("en-US")
  .build();

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

  • Data RecommendationsCluster yang ada dari partner developer akan dihapus.
  • Data dari permintaan akan diuraikan dan disimpan di RecommendationsCluster yang diperbarui. Jika terjadi error, seluruh permintaan akan ditolak dan status yang ada dipertahankan.

Sinkronisasi lintas perangkat

Flag SyncAcrossDevices mengontrol apakah data cluster rekomendasi pengguna dibagikan ke Google TV dan tersedia di seluruh perangkat mereka seperti TV, ponsel, tablet. Agar rekomendasi berfungsi, rekomendasi harus ditetapkan ke true.

Aplikasi media harus memberikan setelan yang jelas untuk mengaktifkan atau menonaktifkan sinkronisasi lintas perangkat. Jelaskan manfaatnya kepada pengguna dan simpan preferensi pengguna satu kali dan terapkan di publishRecommendations Permintaan. Untuk mengoptimalkan fitur lintas perangkat, pastikan aplikasi mendapatkan izin pengguna dan mengaktifkan SyncAcrossDevices ke true.

Menghapus data penemuan video

Untuk menghapus data pengguna secara manual dari server Google TV sebelum periode retensi data 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 rekomendasi saat logout.

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

// If the user revokes the consent to share data with Google TV,
// you must make the following call to remove recommendations data from
// all current google TV devices. Otherwise, the recommendations data persists
// until 60 days later.
client.deleteClusters(
  new DeleteClustersRequest.Builder()
    .setAccountProfile(AccountProfile())
    .setReason(DeleteReason.DELETE_REASON_LOSS_OF_CONSENT)
    .build()
)

Membuat entity

SDK telah menentukan entity yang berbeda untuk mewakili setiap jenis item. Entity berikut didukung untuk cluster Rekomendasi:

  1. MediaActionFeedEntity
  2. MovieEntity
  3. TvShowEntity

Deskripsi

Berikan deskripsi singkat untuk setiap entitas; deskripsi ini akan ditampilkan saat pengguna mengarahkan kursor ke entitas, yang memberi mereka detail tambahan.

URI playBack khusus platform

Buat URI pemutaran untuk setiap platform yang didukung: Android TV, Android, atau iOS. Hal ini memungkinkan sistem memilih URI yang sesuai untuk pemutaran video di platform masing-masing.

Dalam kasus yang jarang terjadi saat URI pemutaran identik untuk semua platform, ulangi untuk setiap platform.

// Required. Set this when you want recommended 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()

// Optional. Set this when you want recommended entities to show up on
// Google TV Android app
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 recommended 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)

// Provide appropriate rating for the system.
val contentRating = new RatingSystem
  .Builder()
  .setAgencyName("MPAA")
  .setRating("PG-13")
  .build()

Gambar poster

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 "Rekomendasi" 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)

Alasan rekomendasi

Secara opsional, berikan alasan rekomendasi yang dapat digunakan oleh Google TV untuk membuat alasan mengapa menyarankan Film atau Acara TV tertentu kepada pengguna.

//Allows us to construct reason: "Because it is top 10 on your Channel"
val topOnPartner = RecommendationReasonTopOnPartner
  .Builder()
  .setNum(10) //any valid integer value
  .build()

//Allows us to construct reason: "Because it is popular on your Channel"
val popularOnPartner = RecommendationReasonPopularOnPartner
  .Builder()
  .build()

//Allows us to construct reason: "New to your channel, or Just added"
val newOnPartner = RecommendationReasonNewOnPartner
  .Builder()
  .build()

//Allows us to construct reason: "Because you watched Star Wars"
val watchedSimilarTitles = RecommendationReasonWatchedSimilarTitles
  .addSimilarWatchedTitleName("Movie or TV Show Title")
  .addSimilarWatchedTitleName("Movie or TV Show Title")
  .Builder()
  .build()

//Allows us to construct reason: "Recommended for you by ChannelName"
val recommendedForUser = RecommendationReasonRecommendedForUser
  .Builder()
  .build()

val watchAgain = RecommendationReasonWatchAgain
  .Builder()
  .build()

val fromUserWatchList = RecommendationReasonFromUserWatchlist
  .Builder()
  .build()

val userLikedOnPartner = RecommendationReasonUserLikedOnPartner
  .Builder()
  .setTitleName("Movie or TV Show Title")
  .build()

val generic = RecommendationReasonGeneric.Builder().build()

Menampilkan periode waktu

Jika entitas hanya boleh tersedia untuk waktu terbatas, tetapkan waktu habis masa berlaku kustom. Tanpa waktu habis masa berlaku yang eksplisit, entitas akan berakhir masa berlakunya secara otomatis dan dihapus setelah 60 hari. Jadi, tetapkan waktu habis masa berlaku hanya jika entitas perlu segera berakhir masa berlakunya. Tentukan beberapa periode ketersediaan tersebut.

val window1 = DisplayTimeWindow
  .Builder()
  .setStartTimeStampMillis(now()+ 1.days.toMillis())
  .setEndTimeStampMillis(now()+ 30.days.toMillis())

val window2 = DisplayTimeWindow
  .Builder()
  .setEndTimeStampMillis(now()+ 30.days.toMillis())

val availabilityTimeWindows: List<DisplayTimeWindow> = listof(window1,window2)

DataFeedElementId

Jika telah mengintegrasikan Katalog media atau feed tindakan Media dengan Google TV, Anda tidak perlu membuat entitas terpisah untuk Film atau Acara TV, dan sebagai gantinya Anda dapat membuat Entitas MediaActionFeed yang menyertakan kolom DataFeedElementId yang diperlukan. ID ini harus unik dan harus cocok dengan ID di Feed Tindakan Media karena membantu mengidentifikasi konten feed yang diserap dan melakukan pencarian konten media.

val id = "dataFeedEleemntId"

MovieEntity

Berikut adalah contoh pembuatan MovieEntity dengan semua kolom wajib diisi:


val movieEntity = MovieEntity.Builder()
  .setName("Movie name")
  .setDescription("A sentence describing movie.")
  .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
  .addPosterImages(images)
  // Suppose the duration is 2 hours, it is 72000000 in milliseconds
  .setDurationMills(72000000)
  .build()

Anda dapat memberikan data tambahan seperti genre, rating konten, tanggal rilis, alasan rekomendasi, dan periode waktu ketersediaan, yang dapat digunakan oleh Google TV untuk tujuan pemfilteran atau tampilan yang ditingkatkan.

val genres = Arrays.asList("Action", "Science fiction");
val rating1 = RatingSystem.Builder().setAgencyName("MPAA").setRating("pg-13").build();
val contentRatings = Arrays.asList(rating1);
//Suppose release date is 11-02-2025
val releaseDate  = 1739233800000L
val movieEntity = MovieEntity.Builder()
  ...
  .addGenres(genres)
  .setReleaseDateEpochMillis(releaseDate)
  .addContentRatings(contentRatings)
  .setRecommendationReason(topOnPartner or watchedSimilarTitles)
  .addAllAvailabilityTimeWindows(availabilityTimeWindows)
  .build()

TvShowEntity

Berikut adalah contoh pembuatan TvShowEntity dengan semua kolom wajib diisi:

val tvShowEntity = TvShowEntity.Builder()
  .setName("Show title")
  .setDescription("A sentence describing TV Show.")
  .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
  .addPosterImages(images)
  .build();

Secara opsional, berikan data tambahan seperti genre, rating konten, alasan rekomendasi, harga penawaran, jumlah season, atau periode waktu ketersediaan, yang dapat digunakan oleh Google TV untuk tujuan pemfilteran atau tampilan yang ditingkatkan.

val genres = Arrays.asList("Action", "Science fiction");
val rating1 = RatingSystem.Builder()
  .setAgencyName("MPAA")
  .setRating("pg-13")
  .build();
val price = Price.Builder()
  .setCurrentPrice("$14.99")
  .setStrikethroughPrice("$16.99")
  .build();
val contentRatings = Arrays.asList(rating1);
val seasonCount = 5;
val tvShowEntity = TvShowEntity.Builder()
  ...
  .addGenres(genres)
  .addContentRatings(contentRatings)
  .setRecommendationReason(topOnPartner or watchedSimilarTitles)
  .addAllAvailabilityTimeWindows(availabilityTimeWindows)
  .setSeasonCount(seasonCount)
  .setPrice(price)
  .build()

MediaActionFeedEntity

Berikut adalah contoh pembuatan MediaActionFeedEntity dengan semua kolom wajib diisi:


val mediaActionFeedEntity = MediaActionFeedEntity.Builder()
  .setDataFeedElementId(id)
  .build()

Secara opsional, berikan data tambahan seperti deskripsi, alasan rekomendasi, dan periode waktu tampilan, yang dapat digunakan oleh Google TV untuk tujuan pemfilteran atau tampilan yang ditingkatkan.

val mediaActionFeedEntity = MediaActionFeedEntity.Builder()
  .setName("Movie name or TV Show name")
  .setDescription("A sentence describing an entity")
  .setRecommendationReason(topOnPartner or watchedSimilarTitles)
  .addPosterImages(images)
  .build()

Dengan menerapkan langkah-langkah ini, developer dapat berhasil mengintegrasikan rekomendasi konten video ke Google TV, meningkatkan penemuan dan engagement pengguna, memberikan pengalaman menonton yang konsisten dan dipersonalisasi bagi pengguna di semua perangkat mereka.