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:
- Buat akun Google Workspace. Ikuti petunjuk di halaman dukungan Google Workspace guna menyiapkan akun untuk organisasi Anda.
- Temukan ID Pelanggan Google Workspace Anda. Temukan ID Pelanggan Anda (misalnya,
C0123abcd) dengan mengikuti langkah-langkah di Menemukan ID pelanggan Anda. - 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.
- 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.
- 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. Autentikasi permintaan Anda. Minta token akses OAuth 2.0 menggunakan cakupan OAuth berikut dan teruskan token di header HTTP
Authorization: Bearerpada 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}-stagingtidak 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_timeavailability_intervalsjauh 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.