Mengintegrasikan rekomendasi menggunakan REST API

Google TV Video Discovery REST API memungkinkan partner mengirim kandidat rekomendasi yang tidak dipersonalisasi ke perangkat Google TV dan perangkat Android TV dari server backend mereka. Mengirim kandidat dari backend akan membuat katalog dan rekomendasi program live partner tetap baru di perangkat ini tanpa mengharuskan pengguna membuka aplikasi partner.

Partner mengirimkan kandidat ke feed rekomendasi. Google membuat setiap feed untuk partner dan mengonfigurasi negara atau wilayah serta bahasa perangkat TV yang menampilkan feed tersebut. Feed dapat berisi film, acara TV, dan program TV live.

Jika Anda ingin memublikasikan rekomendasi yang dipersonalisasi dari perangkat pengguna, lihat Mengintegrasikan rekomendasi di perangkat menggunakan Engage SDK.

Prasyarat

Sebelum melakukan integrasi dengan REST API, pastikan Anda memiliki hal berikut:

  • Project Google Cloud untuk membuat permintaan API.
  • Akun Google Workspace yang terkait dengan organisasi Anda.
  • ID partner dan ID feed rekomendasi Anda, yang diberikan oleh perwakilan partner Google TV Anda selama orientasi. Lihat Feed rekomendasi untuk mengetahui cara penggunaan ID ini.

Dapatkan akses

Akses ke REST API Penemuan Video Google TV dibatasi untuk partner media Google TV yang terdaftar. Setiap pemanggil diautentikasi menggunakan akun layanan Google Cloud yang dipetakan di server ke tepat satu ID partner.

Untuk meminta dan mengonfigurasi akses API, ikuti langkah-langkah berikut:

  1. Buat akun Google Workspace. Ikuti petunjuk di halaman dukungan Google Workspace guna menyiapkan akun untuk organisasi Anda.
  2. Temukan ID Pelanggan Google Workspace Anda. Temukan ID Pelanggan Anda (misalnya, C0123abcd) dengan mengikuti langkah-langkah di Menemukan ID pelanggan Anda.
  3. Buat project dan akun layanan Google Cloud. Di Konsol Google Cloud di bagian organisasi Google Workspace, buat project Google Cloud dan akun layanan untuk server backend Anda.
  4. Minta orientasi partner. Berikan ID Pelanggan Google Workspace, ID Project Google Cloud, dan alamat email akun layanan (atau ID numerik unik) kepada perwakilan partner Google TV Anda, beserta negara atau wilayah dan bahasa perangkat TV yang ingin Anda kirimi kandidat. Perwakilan partner Google TV Anda akan memberi tahu Anda setelah memetakan organisasi, project, dan akun layanan Google Workspace ke ID partner Anda, dan memberi Anda ID feed rekomendasi yang dibuat untuk partner Anda.
  5. Aktifkan API dan buat kredensial. Setelah perwakilan Anda mengonfirmasi bahwa akses telah diberikan, aktifkan Google TV Video Discovery API (tvvideodiscovery.googleapis.com) di project Google Cloud Anda dan buat kredensial OAuth 2.0 untuk akun layanan Anda.
  6. Autentikasi permintaan Anda. Minta token akses OAuth 2.0 menggunakan cakupan OAuth berikut dan teruskan token di header HTTP Authorization: Bearer pada setiap panggilan:

    https://www.googleapis.com/auth/tvvideodiscovery
    

Batas kapasitas

Permintaan ke replaceCandidates tunduk pada batas kapasitas per project dan batas payload per permintaan berikut:

Batas Nilai
Permintaan per menit per project Google Cloud 5
Permintaan per hari per project Google Cloud 100
RecommendationCandidate item per permintaan 1 hingga 25

Permintaan ke feed staging mengurangi kuota yang sama dengan permintaan ke feed produksi yang sesuai.

Feed rekomendasi

API ini mengatur kandidat rekomendasi ke dalam feed rekomendasi. Feed diidentifikasi dengan nama resource dengan format berikut:

partners/{partner}/recommendationsFeeds/{recommendationsFeed}

Partner

{partner} adalah ID partner yang ditetapkan Google kepada Anda selama orientasi. Akun layanan yang Anda gunakan untuk melakukan autentikasi dipetakan ke tepat satu ID partner. Permintaan yang menyebutkan partner lain akan gagal dengan 403 PERMISSION_DENIED.

ID Feed

{recommendationsFeed} adalah ID feed yang dibuat Google untuk Anda selama aktivasi. Anda tidak dapat membuat feed dengan API.

Setiap feed menargetkan audiens yang dikonfigurasi Google saat membuat feed:

  • Negara atau wilayah: tempat kandidat feed ditampilkan.
  • Bahasa perangkat TV: bahasa yang ditetapkan oleh pengguna yang ditarget di perangkat TV mereka. Bahasa ini bukan bahasa teks yang Anda kirim. Untuk menyediakan teks dalam lebih dari satu bahasa, lihat LocalizedString.

Google memutuskan tempat kandidat feed muncul di perangkat Google TV dan Android TV. Anda mengirim kandidat ke setiap feed dengan cara yang sama.

Feed staging

Setiap feed memiliki feed staging yang cocok bernama {recommendationsFeed}-staging. Feed staging hanya ditayangkan ke akun pengujian dalam daftar yang diizinkan. Gunakan feed ini untuk memvalidasi integrasi sebelum Anda mengirim kandidat ke feed produksi.

Feed staging menggunakan endpoint, kredensial, validasi permintaan, dan kuota yang sama dengan feed produksi. Hanya audiensnya yang berbeda.

Penggantian

Feed adalah unit penggantian. Setiap panggilan replaceCandidates akan menggantikan semua kandidat yang sebelumnya disimpan untuk feed tersebut dan membiarkan feed lainnya tidak tersentuh.

Mengganti kandidat rekomendasi

Gunakan metode partners.recommendationsFeeds.replaceCandidates untuk mengirim daftar lengkap kandidat rekomendasi untuk satu feed.

Permintaan HTTP

POST https://tvvideodiscovery.googleapis.com/v1/{name=partners/*/recommendationsFeeds/*}:replaceCandidates

Jalur URL berisi nama resource feed yang kandidatnya diganti. Isi permintaan berisi setiap kolom yang bukan bagian dari jalur URL.

Parameter jalur

Parameter Deskripsi
name Wajib. Nama resource feed, dalam format partners/{partner}/recommendationsFeeds/{recommendationsFeed}. {partner} harus berupa ID partner yang dipetakan ke akun layanan Anda. {recommendationsFeed} harus berupa ID feed yang dibuat Google untuk partner tersebut, atau ID feed tersebut dengan akhiran -staging.

ReplaceCandidatesRequest

Isi permintaan JSON memiliki struktur berikut:

Kolom Jenis Wajib Deskripsi
recommendation_candidates array of RecommendationCandidate Ya Daftar berisi 1 hingga 25 item RecommendationCandidate. Kandidat ini menggantikan kandidat feed saat ini.

Skema kandidat

Setiap item di recommendation_candidates adalah objek RecommendationCandidate yang berisi satu payload jenis kandidat, alasan rekomendasi opsional, dan periode ketersediaan tampilan opsional.

RecommendationCandidate

Objek RecommendationCandidate berisi tepat satu kolom payload jenis media, alasan rekomendasi opsional, dan interval ketersediaan opsional.

Kolom union candidate_type

candidate_type wajib diisi: tetapkan hanya salah satu kolom berikut. Kolom ini bersifat eksklusif, dan kandidat yang tidak menetapkan atau menetapkan lebih dari satu akan ditolak. Tidak ada kunci candidate_type di JSON; tetapkan kolom yang dipilih langsung pada objek RecommendationCandidate.

Kolom Jenis Deskripsi
movie_candidate MovieCandidate Film on-demand (lihat MovieCandidate).
tv_show_candidate TvShowCandidate Acara TV di tingkat acara (lihat TvShowCandidate).
live_tv_program_candidate LiveTvProgramCandidate Siaran TV live atau acara yang di-streaming sesuai jadwal (lihat LiveTvProgramCandidate).

Konteks dan ketersediaan

Kedua kolom bersifat opsional:

Kolom Jenis Wajib Deskripsi
recommendation_contexts array of RecommendationContext Tidak Alasan kandidat direkomendasikan, dan durasi berlakunya setiap alasan (lihat RecommendationContext).
availability_intervals array of Interval Tidak Rentang waktu saat kandidat dapat ditampilkan (lihat Interval). Setiap rentang waktu dimulai pada start_time (inklusif) dan berakhir pada end_time (eksklusif). Jika tidak ditetapkan, kandidat akan memenuhi syarat selama disimpan. Kandidat yang semua jendelanya berada di masa lalu tidak akan pernah ditampilkan.

MovieCandidate

Objek MovieCandidate mewakili film on-demand:

Kolom Jenis Wajib Deskripsi
title LocalizedString Ya Judul film (lihat LocalizedString). Setiap nilai adalah 1 hingga 100 poin kode Unicode dan ditampilkan seperti yang dikirim.
description LocalizedString Ya Deskripsi singkat film (lihat LocalizedString). Setiap nilai adalah 1 hingga 400 poin kode Unicode.
localized_media_images array of LocalizedMediaImage Ya Gambar poster 16:9, satu entri per bahasa (lihat LocalizedMediaImage). Harus berisi minimal satu gambar. Berikan sumber terbesar yang tersedia; sebaiknya gunakan 1920x1080 piksel.
localized_provider_playback_uris array of LocalizedProviderPlaybackUri Ya Deep link per platform dan per bahasa (lihat LocalizedProviderPlaybackUri). Setidaknya satu entri harus mencantumkan PLATFORM_ANDROID_TV.
release_date Date Ya Tanggal rilis film (lihat Date).
external_entity_ids array of ExternalEntityId Tidak ID katalog eksternal untuk pencocokan entity (lihat ExternalEntityId). Maksimal satu entri per jenis ID.
duration string (Duration) Tidak Durasi film (lihat Duration). Misalnya, "7200s" untuk 2 jam.
content_ratings array of ContentRating Tidak Rating konten resmi (lihat ContentRating).

TvShowCandidate

Objek TvShowCandidate mewakili acara TV di tingkat acara. Perangkat Google TV dan Android TV menampilkan kartu untuk acara; gunakan deep link untuk memutuskan apakah pemutaran dimulai di halaman acara atau di episode tertentu.

Kolom Jenis Wajib Deskripsi
title LocalizedString Ya Judul acara TV (lihat LocalizedString). Setiap nilai adalah 1 hingga 100 poin kode Unicode dan ditampilkan seperti yang dikirim.
description LocalizedString Ya Deskripsi singkat acara TV (lihat LocalizedString). Setiap nilai terdiri dari 1 hingga 400 poin kode Unicode.
localized_media_images array of LocalizedMediaImage Ya Gambar poster 16:9, satu entri per bahasa (lihat LocalizedMediaImage). Harus berisi minimal satu gambar. Berikan sumber terbesar yang tersedia; sebaiknya gunakan 1920x1080 piksel.
localized_provider_playback_uris array of LocalizedProviderPlaybackUri Ya Deep link per platform dan per bahasa (lihat LocalizedProviderPlaybackUri). Setidaknya satu entri harus mencantumkan PLATFORM_ANDROID_TV. uri dapat mengarah ke halaman acara atau ke episode.
first_episode_air_date Date Ya Tanggal disiarkan episode pertama (lihat Date).
external_entity_ids array of ExternalEntityId Tidak ID katalog eksternal untuk pencocokan entity (lihat ExternalEntityId). Maksimal satu entri per jenis ID.
season_count integer (int32) Tidak Jumlah season yang tersedia di layanan Anda.
content_ratings array of ContentRating Tidak Rating konten resmi (lihat ContentRating).

LiveTvProgramCandidate

Objek LiveTvProgramCandidate mewakili siaran TV live terjadwal atau acara yang di-streaming. Jendela siaran adalah bagian dari kandidat dan terpisah dari availability_intervals kandidat induk, yang mengontrol kapan kartu dapat ditampilkan.

Kolom Jenis Wajib Deskripsi
title LocalizedString Ya Judul program TV live (lihat LocalizedString). Setiap nilai terdiri dari 1 hingga 100 poin kode Unicode dan ditampilkan seperti yang dikirim.
description LocalizedString Ya Deskripsi singkat program TV live (lihat LocalizedString). Setiap nilai adalah 1 hingga 400 poin kode Unicode.
localized_media_images array of LocalizedMediaImage Ya Gambar poster 16:9, satu entri per bahasa (lihat LocalizedMediaImage). Harus berisi minimal satu gambar. Berikan sumber terbesar yang tersedia; sebaiknya gunakan 1920x1080 piksel.
localized_provider_playback_uris array of LocalizedProviderPlaybackUri Ya Deep link per platform dan per bahasa (lihat LocalizedProviderPlaybackUri). Setidaknya satu entri harus mencantumkan PLATFORM_ANDROID_TV.
broadcast_interval Interval Ya Awal dan akhir siaran program (lihat Interval). start_time dan end_time wajib diisi.
external_entity_ids array of ExternalEntityId Tidak ID katalog eksternal untuk pencocokan entity (lihat ExternalEntityId). Maksimal satu entri per jenis ID.
content_ratings array of ContentRating Tidak Rating konten resmi (lihat ContentRating).

Skema pendukung

Payload kandidat merujuk ke objek bersama berikut untuk teks yang dilokalkan, deep link, poster, ID eksternal, alasan rekomendasi, interval tampilan, rating konten, serta jenis tanggal dan waktu yang umum.

LocalizedString

Objek LocalizedString membawa teks yang sama dalam satu atau beberapa bahasa. Setiap nilai diberi tag dengan bahasanya sehingga perangkat Google TV dan Android TV dapat menampilkan teks yang cocok dengan bahasa perangkat TV pengguna:

Kolom Jenis Wajib Deskripsi
values array of LocalizedText Ya Teks dalam setiap bahasa yang Anda berikan (lihat LocalizedText). Harus berisi setidaknya satu nilai.

LocalizedText

Objek LocalizedText adalah teks dalam satu bahasa:

Kolom Jenis Wajib Deskripsi
text string Ya Teks dalam bahasa yang diberikan oleh language_code.
language_code string Ya Kode bahasa BCP-47 text, seperti "en-US" atau "sr-Latn".

LocalizedMediaImage

Objek LocalizedMediaImage menyambungkan gambar dengan bahasa teks apa pun dalam gambar:

Kolom Jenis Wajib Deskripsi
language_code string Ya Kode bahasa BCP-47 teks dalam gambar, seperti "en-US" atau "sr-Latn".
image MediaImage Ya Gambar 16:9 (lihat MediaImage). Berikan sumber terbesar yang tersedia; direkomendasikan 1920x1080 piksel.

LocalizedProviderPlaybackUri

Objek LocalizedProviderPlaybackUri menyambungkan deep link dengan bahasa konten yang dibuka dan aplikasi yang membukanya:

Kolom Jenis Wajib Deskripsi
playback_uri PlaybackUri Ya Deep link dan platform yang berlaku (lihat PlaybackUri).
language_code string Ya Kode bahasa BCP-47 konten yang dibuka oleh deep link, seperti "en-US" atau "sr-Latn".
package_name string Ya Nama paket aplikasi Android yang digunakan untuk membuka deep link (misalnya, "com.example.tvapp").

PlaybackUri

Objek PlaybackUri menentukan deep link dan platform targetnya:

Kolom Jenis Wajib Deskripsi
uri string Ya URI deep link yang memulai pemutaran kandidat di aplikasi Anda.
platforms array of string (enum) Ya Platform tempat deep link ini berlaku. Nilai yang diizinkan: PLATFORM_UNSPECIFIED, PLATFORM_ANDROID_TV, PLATFORM_ANDROID, PLATFORM_IOS. Sertakan PLATFORM_ANDROID_TV untuk perangkat Google TV dan Android TV.

MediaImage

Objek MediaImage menentukan URL gambar, dimensi pikselnya, dan teks aksesibilitas:

Kolom Jenis Wajib Deskripsi
url string Ya URL HTTPS gambar yang dapat diakses secara publik.
width integer Ya Lebar gambar yang tidak diubah (maksimum) dalam piksel.
height integer Ya Tinggi gambar yang tidak diubah (maksimum) dalam piksel.
accessibility_text string Ya Teks aksesibilitas (alternatif) yang mendeskripsikan gambar.

ExternalEntityId

Objek ExternalEntityId memetakan kandidat ke ID dalam katalog eksternal. Tetapkan tepat satu kolom berikut per entri, dan sertakan maksimal satu entri per jenis ID dalam daftar external_entity_ids kandidat:

Kolom Jenis Wajib Deskripsi
tms_root_id string Salah satu ID root TMS Gracenote. Mengidentifikasi judul: film, acara TV, atau episode.
tms_id string Salah satu ID varian TMS Gracenote. Mengidentifikasi edisi atau listingan siaran.
data_feed_element_id string Salah satu ID Entitas dari feed data Media Actions Anda. Nilai ini tidak terkait dengan segmen {recommendationsFeed} dari nama resource.

RecommendationContext

Objek RecommendationContext menjelaskan alasan kandidat direkomendasikan dan berapa lama penjelasan tersebut berlaku:

Kolom Jenis Wajib Deskripsi
recommendation_reason RecommendationReason Tidak Alasan kandidat direkomendasikan (lihat RecommendationReason).
validity_interval Interval Tidak Rentang waktu saat konteks ini berlaku (lihat Interval). Misalnya, kandidat baru hanya berlaku untuk jumlah hari yang terbatas. Jika tidak ditetapkan, konteks akan berlaku selama kandidat disimpan.

RecommendationReason

Objek RecommendationReason membawa satu alasan. Tetapkan hanya salah satu dari kolom berikut:

Kolom Jenis Wajib Deskripsi
top_on_partner object Salah satu Kandidat adalah item teratas yang diberi peringkat di layanan Anda. Berisi satu kolom bilangan bulat positif rank (misalnya, {"rank": 1} untuk "Top 1 on Partner").
popular_on_partner object Salah satu Kandidat tersebut populer di layanan Anda. Teruskan objek kosong ({}).
new_on_partner object Salah satu Kandidat ini baru di layanan Anda. Teruskan objek kosong ({}).
generic object Salah satu Alasan kustom. Berisi satu kolom LocalizedString generic_reason (lihat LocalizedString). Setiap nilai adalah 1 hingga 100 poin kode Unicode.

ContentRating

Objek ContentRating mewakili rating konten resmi yang ditetapkan oleh lembaga rating:

Kolom Jenis Wajib Deskripsi
rating_system string Ya Lembaga atau sistem rating, misalnya "MPAA", "BBFC", atau "CBFC".
rating_value string Ya Rating seperti yang ditentukan oleh rating_system, misalnya "PG-13" atau "U/A 13+".

Timestamp

Timestamp dienkode dalam JSON sebagai string RFC 3339 dalam UTC dengan akhiran Z, misalnya "2026-10-01T18:00:00Z". Pecahan detik diizinkan, misalnya "2026-10-01T18:00:00.500Z".

Duration

Duration dienkode dalam JSON sebagai string yang berisi jumlah detik diikuti dengan akhiran s, misalnya "7200s" untuk 2 jam. Detik pecahan diizinkan, misalnya "5400.5s".

Date

Date adalah tanggal kalender tanpa zona waktu. Objek ini dienkode dalam JSON sebagai objek dengan kolom berikut:

Kolom Jenis Wajib Deskripsi
year integer Ya Tahun tanggal, misalnya 2025.
month integer Tidak Bulan dalam setahun, dari 1 hingga 12. Tetapkan ke 0 atau hapus jika bulan tidak diketahui.
day integer Tidak Hari dalam sebulan, dari 1 hingga 31, dan berlaku untuk tahun dan bulan yang ditentukan. Tetapkan ke 0 atau hapus jika hari tidak diketahui. Memerlukan month.

Misalnya, {"year": 2025, "month": 1, "day": 17} mewakili 17 Januari 2025, {"year": 2025, "month": 1} mewakili Januari 2025 dengan hari yang tidak diketahui, dan {"year": 2025} mewakili tanggal pada tahun 2025 dengan bulan dan hari yang tidak diketahui.

Interval

Interval adalah rentang waktu setengah terbuka yang dimulai pada start_time (inklusif) dan berakhir pada end_time (eksklusif). Waktu T berada di dalam interval saat start_time <= T dan T < end_time.

Kolom Jenis Wajib Deskripsi
start_time string (Timestamp) Ya Awal jendela inklusif (lihat Timestamp), misalnya "2026-10-01T18:00:00Z".
end_time string (Timestamp) Ya Akhir jendela eksklusif (lihat Timestamp), misalnya "2026-10-01T21:00:00Z". Harus lebih lambat dari start_time.

Contoh permintaan

Contoh berikut mengganti kandidat feed in-en-cricket dari partner example-partner dengan tiga kandidat (film, acara TV, dan program TV live). Film ini menampilkan teks dalam dua bahasa:

curl -X POST \
  "https://tvvideodiscovery.googleapis.com/v1/partners/example-partner/recommendationsFeeds/in-en-cricket:replaceCandidates" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "recommendation_candidates": [
      {
        "movie_candidate": {
          "title": {
            "values": [
              {
                "text": "Example Action Movie",
                "language_code": "en-US"
              },
              {
                "text": "Película de acción de ejemplo",
                "language_code": "es-419"
              }
            ]
          },
          "description": {
            "values": [
              {
                "text": "An example action movie synopsis.",
                "language_code": "en-US"
              },
              {
                "text": "Sinopsis de una película de acción de ejemplo.",
                "language_code": "es-419"
              }
            ]
          },
          "localized_media_images": [
            {
              "language_code": "en-US",
              "image": {
                "url": "https://www.example.com/images/movie-1001-16x9-en.jpg",
                "width": 1920,
                "height": 1080,
                "accessibility_text": "Artwork for Example Action Movie"
              }
            },
            {
              "language_code": "es-419",
              "image": {
                "url": "https://www.example.com/images/movie-1001-16x9-es.jpg",
                "width": 1920,
                "height": 1080,
                "accessibility_text": "Imagen de Película de acción de ejemplo"
              }
            }
          ],
          "localized_provider_playback_uris": [
            {
              "playback_uri": {
                "uri": "https://www.example.com/watch/movie-1001?lang=en",
                "platforms": ["PLATFORM_ANDROID_TV", "PLATFORM_ANDROID"]
              },
              "language_code": "en-US",
              "package_name": "com.example.tvapp"
            },
            {
              "playback_uri": {
                "uri": "https://www.example.com/watch/movie-1001?lang=es",
                "platforms": ["PLATFORM_ANDROID_TV", "PLATFORM_ANDROID"]
              },
              "language_code": "es-419",
              "package_name": "com.example.tvapp"
            }
          ],
          "release_date": {
            "year": 2025,
            "month": 11,
            "day": 14
          },
          "external_entity_ids": [
            {
              "tms_root_id": "MV001234560000"
            }
          ],
          "duration": "7200s",
          "content_ratings": [
            {
              "rating_system": "MPAA",
              "rating_value": "PG-13"
            }
          ]
        },
        "recommendation_contexts": [
          {
            "recommendation_reason": {
              "top_on_partner": {
                "rank": 1
              }
            }
          }
        ],
        "availability_intervals": [
          {
            "start_time": "2026-11-01T00:00:00Z",
            "end_time": "2026-12-01T00:00:00Z"
          }
        ]
      },
      {
        "tv_show_candidate": {
          "title": {
            "values": [
              {
                "text": "Example Drama Series",
                "language_code": "en-US"
              }
            ]
          },
          "description": {
            "values": [
              {
                "text": "An example drama series synopsis.",
                "language_code": "en-US"
              }
            ]
          },
          "localized_media_images": [
            {
              "language_code": "en-US",
              "image": {
                "url": "https://www.example.com/images/show-2002-16x9.jpg",
                "width": 1920,
                "height": 1080,
                "accessibility_text": "Artwork for Example Drama Series"
              }
            }
          ],
          "localized_provider_playback_uris": [
            {
              "playback_uri": {
                "uri": "https://www.example.com/watch/show-2002",
                "platforms": ["PLATFORM_ANDROID_TV"]
              },
              "language_code": "en-US",
              "package_name": "com.example.tvapp"
            }
          ],
          "first_episode_air_date": {
            "year": 2024,
            "month": 3,
            "day": 8
          },
          "external_entity_ids": [
            {
              "data_feed_element_id": "show-2002"
            }
          ],
          "season_count": 3,
          "content_ratings": [
            {
              "rating_system": "TV_PG",
              "rating_value": "TV-14"
            }
          ]
        },
        "recommendation_contexts": [
          {
            "recommendation_reason": {
              "new_on_partner": {}
            },
            "validity_interval": {
              "start_time": "2026-11-01T00:00:00Z",
              "end_time": "2026-11-15T00:00:00Z"
            }
          }
        ],
        "availability_intervals": [
          {
            "start_time": "2026-11-01T00:00:00Z",
            "end_time": "2026-12-01T00:00:00Z"
          }
        ]
      },
      {
        "live_tv_program_candidate": {
          "title": {
            "values": [
              {
                "text": "Championship Live Broadcast",
                "language_code": "en-US"
              }
            ]
          },
          "description": {
            "values": [
              {
                "text": "Live coverage of the championship match.",
                "language_code": "en-US"
              }
            ]
          },
          "localized_media_images": [
            {
              "language_code": "en-US",
              "image": {
                "url": "https://www.example.com/images/live-prog-500-16x9.jpg",
                "width": 1920,
                "height": 1080,
                "accessibility_text": "Artwork for Championship Live Broadcast"
              }
            }
          ],
          "localized_provider_playback_uris": [
            {
              "playback_uri": {
                "uri": "https://www.example.com/live/sports-1",
                "platforms": ["PLATFORM_ANDROID_TV"]
              },
              "language_code": "en-US",
              "package_name": "com.example.tvapp"
            }
          ],
          "broadcast_interval": {
            "start_time": "2026-11-15T18:00:00Z",
            "end_time": "2026-11-15T21:00:00Z"
          },
          "external_entity_ids": [
            {
              "tms_id": "EP012345670001"
            }
          ],
          "content_ratings": [
            {
              "rating_system": "TV_PG",
              "rating_value": "TV-PG"
            }
          ]
        },
        "recommendation_contexts": [
          {
            "recommendation_reason": {
              "generic": {
                "generic_reason": {
                  "values": [
                    {
                      "text": "Live this weekend",
                      "language_code": "en-US"
                    }
                  ]
                }
              }
            }
          }
        ],
        "availability_intervals": [
          {
            "start_time": "2026-11-14T18:00:00Z",
            "end_time": "2026-11-15T21:00:00Z"
          }
        ]
      }
    ]
  }'

Perilaku respons dan penggantian

Bagian ini menjelaskan respons HTTP yang ditampilkan oleh replaceCandidates dan cara setiap panggilan memperbarui kandidat yang disimpan.

ReplaceCandidatesResponse

Jika permintaan berhasil, API akan menampilkan HTTP 200 OK dengan isi ReplaceCandidatesResponse:

Kolom Jenis Deskripsi
replaced_candidates_count integer (int32) Jumlah kandidat yang diganti.

Untuk contoh permintaan sebelumnya, responsnya adalah:

{
  "replaced_candidates_count": 3
}

Perilaku penggantian

Memahami cara replaceCandidates memperbarui kandidat yang disimpan sangat penting untuk mendesain integrasi Anda:

  • Penggantian penuh per feed. Setiap panggilan akan sepenuhnya menggantikan daftar kandidat yang disimpan sebelumnya untuk feed yang disebutkan di jalur URL. Selalu kirimkan kumpulan lengkap kandidat aktif untuk feed tersebut.
  • Feed lainnya tidak berubah. Feed yang tidak Anda kirimi kandidat akan tetap tidak berubah hingga Anda melakukannya. Misalnya, mengganti kandidat dari satu feed tidak akan mengubah kandidat yang disimpan untuk feed lain, dan mengganti kandidat {recommendationsFeed}-staging tidak akan mengubah {recommendationsFeed}.
  • Satu panggilan per feed. Untuk memperbarui beberapa feed, lakukan satu panggilan per feed. Panggilan tersebut bersifat independen: jika salah satu gagal, feed lainnya akan mempertahankan kandidat barunya dan Anda hanya akan mencoba ulang panggilan yang gagal.
  • Kirim ulang feed aktif setidaknya setiap 30 hari. Meskipun katalog Anda untuk feed tidak berubah, kirim ulang setiap feed aktif setidaknya sekali setiap 30 hari (atau sesuai jadwal harian atau mingguan reguler dengan jitter acak) agar kandidat Anda tetap aktif dan tidak habis masa berlakunya. Menetapkan end_time availability_intervals jauh di masa mendatang tidak menggantikan pengiriman ulang berkala.
  • Eksekusi atom. API menerapkan permintaan secara atomik. Jika ada kandidat yang gagal divalidasi, API akan menolak seluruh permintaan dan feed akan mempertahankan kandidat sebelumnya.