L'API REST Google TV Video Discovery consente ai partner di inviare suggerimenti candidati non personalizzati ai dispositivi Google TV e Android TV dai loro server di backend. L'invio di candidati dal backend mantiene aggiornati il catalogo e i consigli di programmazione in diretta di un partner su questi dispositivi senza richiedere agli utenti di aprire l'app del partner.
I partner inviano i candidati ai feed dei contenuti consigliati. Google crea ogni feed per il partner e configura i paesi o le regioni e le lingue dei dispositivi TV in cui viene mostrato il feed. Un feed può contenere film, programmi TV e programmi TV in diretta.
Se vuoi pubblicare suggerimenti personalizzati dal dispositivo dell'utente, consulta Integra i suggerimenti on-device utilizzando l'SDK Engage.
Prerequisiti
Prima di eseguire l'integrazione con l'API REST, assicurati di avere quanto segue:
- Un progetto Google Cloud da cui effettuare richieste API.
- Un account Google Workspace associato alla tua organizzazione.
- Il tuo ID partner e gli ID dei feed di consigli, forniti dal tuo rappresentante partner di Google TV durante l'onboarding. Consulta la sezione Feed dei consigli per scoprire come vengono utilizzati questi ID.
Ottieni accesso
L'accesso all'API REST Google TV Video Discovery è limitato ai partner di Google TV Media registrati. Ogni chiamante viene autenticato utilizzando un account di servizio Google Cloud mappato sul server esattamente a un ID partner.
Per richiedere e configurare l'accesso API, segui questi passaggi:
- Crea un account Google Workspace. Segui le istruzioni riportate nella pagina di assistenza Google Workspace per configurare un account per la tua organizzazione.
- Individua il tuo ID cliente Google Workspace. Trova il tuo ID cliente (ad esempio
C0123abcd) seguendo i passaggi descritti in Trova il tuo ID cliente. - Crea un progetto Google Cloud e un service account. Nella console Google Cloud, nella tua organizzazione Google Workspace, crea un progetto Google Cloud e un service account per il tuo server di backend.
- Richiedi l'onboarding dei partner. Fornisci il tuo ID cliente Google Workspace, l'ID progetto Google Cloud e l'indirizzo email del service account (o l'ID numerico univoco) al tuo rappresentante partner di Google TV, insieme ai paesi o alle regioni e alle lingue dei dispositivi TV a cui vuoi inviare i candidati. Il tuo rappresentante partner di Google TV ti avvisa dopo aver mappato l'organizzazione, il progetto e l'account di servizio Google Workspace al tuo ID partner e ti fornisce gli ID dei feed di contenuti consigliati creati per il tuo partner.
- Abilita l'API e genera le credenziali. Dopo che il tuo rappresentante
ha confermato che l'accesso è stato concesso, attiva l'API Google TV Video Discovery
(
tvvideodiscovery.googleapis.com) nel tuo progetto Google Cloud e genera le credenziali OAuth 2.0 per il tuo service account. Autentica le tue richieste. Richiedi i token di accesso OAuth 2.0 utilizzando il seguente ambito OAuth e passa il token nell'intestazione HTTP
Authorization: Bearerin ogni chiamata:https://www.googleapis.com/auth/tvvideodiscovery
Limiti di frequenza
Le richieste a replaceCandidates sono soggette ai seguenti limiti di frequenza per progetto e limiti di payload per richiesta:
| Limite | Valore |
|---|---|
| Richieste al minuto per progetto Google Cloud | 5 |
| Richieste al giorno per progetto Google Cloud | 100 |
RecommendationCandidate elementi per richiesta |
1-25 |
Le richieste a un feed di gestione temporanea vengono conteggiate ai fini della stessa quota delle richieste al feed di produzione corrispondente.
Feed di consigli
L'API organizza i candidati ai consigli in feed di consigli. Un feed è identificato da un nome della risorsa con il seguente formato:
partners/{partner}/recommendationsFeeds/{recommendationsFeed}
Partner
{partner} è l'ID partner che Google ti assegna durante l'onboarding. Il service account con cui esegui l'autenticazione è mappato esattamente a un ID partner.
Le richieste che indicano un altro partner non vanno a buon fine e restituiscono l'errore 403 PERMISSION_DENIED.
ID feed
{recommendationsFeed} è un ID feed che Google crea per te durante l'onboarding. Non puoi creare feed con l'API.
Ogni feed ha come target un segmento di pubblico configurato da Google al momento della creazione del feed:
- Paesi o regioni: dove vengono mostrati i candidati del feed.
- Lingue del dispositivo TV: le lingue impostate dagli utenti target sul loro dispositivo TV. Non si tratta della lingua del testo che invii. Per fornire il testo in più lingue, consulta
LocalizedString.
Google decide dove vengono visualizzati i candidati di un feed sui dispositivi Google TV e Android TV. Puoi inviare i candidati a ogni feed nello stesso modo.
Feed di gestione temporanea
Ogni feed ha un feed di gestione temporanea corrispondente denominato {recommendationsFeed}-staging. Un feed di gestione temporanea viene pubblicato solo per gli account di test in una lista consentita. Utilizzalo per convalidare l'integrazione prima di inviare i candidati al feed di produzione.
I feed di gestione temporanea utilizzano lo stesso endpoint, le stesse credenziali, la stessa convalida delle richieste e la stessa quota dei feed di produzione. Cambia solo il pubblico.
Sostituzione
Il feed è l'unità di sostituzione. Ogni chiamata replaceCandidates sostituisce tutti i candidati precedentemente memorizzati per quel feed e lascia invariati tutti gli altri feed.
Sostituisci i candidati per i suggerimenti
Utilizza il metodo partners.recommendationsFeeds.replaceCandidates per inviare l'elenco completo dei candidati ai consigli per un feed.
Richiesta HTTP
POST https://tvvideodiscovery.googleapis.com/v1/{name=partners/*/recommendationsFeeds/*}:replaceCandidates
Il percorso dell'URL contiene il nome della risorsa del feed i cui candidati vengono sostituiti. Il corpo della richiesta contiene tutti i campi che non fanno parte del percorso dell'URL.
Parametri del percorso
| Parametro | Descrizione |
|---|---|
name |
Obbligatorio. Il nome della risorsa del feed, nel formato partners/{partner}/recommendationsFeeds/{recommendationsFeed}. {partner} deve essere l'ID partner a cui è mappato il tuo service account. {recommendationsFeed} deve essere un ID feed creato da Google per quel partner o l'ID feed con il suffisso -staging. |
ReplaceCandidatesRequest
Il corpo della richiesta JSON ha la seguente struttura:
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
recommendation_candidates |
array of RecommendationCandidate |
Sì | Un elenco di 1-25 elementi RecommendationCandidate. Questi candidati sostituiscono quelli attuali del feed. |
Schemi candidati
Ogni elemento in recommendation_candidates è un oggetto RecommendationCandidate che contiene un payload di tipo candidato, motivi dei suggerimenti facoltativi e finestre di disponibilità di visualizzazione facoltative.
RecommendationCandidate
Un oggetto RecommendationCandidate contiene esattamente un campo payload del tipo di media, motivi dei contenuti consigliati facoltativi e intervalli di disponibilità facoltativi.
Campo unione candidate_type
candidate_type è obbligatorio: imposta esattamente uno dei seguenti campi. I campi si escludono a vicenda e un candidato che non ne imposta nessuno o ne imposta più di uno viene rifiutato. Non esiste una chiave candidate_type nel JSON; imposta il campo scelto direttamente sull'oggetto RecommendationCandidate.
| Campo | Tipo | Descrizione |
|---|---|---|
movie_candidate |
MovieCandidate |
Un film on demand (vedi MovieCandidate). |
tv_show_candidate |
TvShowCandidate |
Un programma TV a livello di programma (vedi TvShowCandidate). |
live_tv_program_candidate |
LiveTvProgramCandidate |
Un evento in streaming o una trasmissione TV in diretta programmata (vedi LiveTvProgramCandidate). |
Contesto e disponibilità
Entrambi i campi sono facoltativi:
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
recommendation_contexts |
array of RecommendationContext |
No | Il motivo per cui il candidato è consigliato e per quanto tempo si applica ogni motivo (vedi RecommendationContext). |
availability_intervals |
array of Interval |
No | Finestre temporali durante le quali il candidato può essere mostrato (vedi Interval). Ogni finestra inizia con il relativo start_time (incluso) e termina con il relativo end_time (escluso). Se non viene impostato, il candidato è idoneo per tutto il tempo in cui viene archiviato. Un candidato le cui finestre sono tutte nel passato non viene mai mostrato. |
MovieCandidate
L'oggetto MovieCandidate rappresenta un film on demand:
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
title |
LocalizedString |
Sì | Titolo del film (vedi LocalizedString). Ogni valore è compreso tra 1 e 100 punti di codice Unicode e viene mostrato così come è stato inviato. |
description |
LocalizedString |
Sì | Breve descrizione del film (vedi LocalizedString). Ogni valore è compreso tra 1 e 400 punti di codice Unicode. |
localized_media_images |
array of LocalizedMediaImage |
Sì | Immagini artwork 16:9, una voce per lingua (vedi LocalizedMediaImage). Deve contenere almeno un'immagine. Fornisci la sorgente più grande disponibile; sono consigliati 1920 x 1080 pixel. |
localized_provider_playback_uris |
array of LocalizedProviderPlaybackUri |
Sì | Deep link per piattaforma e per lingua (vedi LocalizedProviderPlaybackUri). Almeno una voce deve elencare PLATFORM_ANDROID_TV. |
release_date |
Date |
Sì | Data di uscita del film (vedi Date). |
external_entity_ids |
array of ExternalEntityId |
No | Identificatori di cataloghi esterni per la corrispondenza delle entità (vedi ExternalEntityId). Al massimo una voce per tipo di identificatore. |
duration |
string (Duration) |
No | La durata del film (vedi Duration). Ad esempio, "7200s" per 2 ore. |
content_ratings |
array of ContentRating |
No | Classificazioni dei contenuti ufficiali (vedi ContentRating). |
TvShowCandidate
L'oggetto TvShowCandidate rappresenta un programma TV a livello di programma. I dispositivi Google TV e Android TV mostrano una scheda per il programma; utilizza il deep link per decidere se la riproduzione inizia nella pagina del programma o in un episodio specifico.
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
title |
LocalizedString |
Sì | Titolo del programma TV (vedi LocalizedString). Ogni valore è compreso tra 1 e 100 punti di codice Unicode e viene mostrato così come è stato inviato. |
description |
LocalizedString |
Sì | Breve descrizione del programma TV (vedi LocalizedString). Ogni valore è compreso tra 1 e 400 punti di codice Unicode. |
localized_media_images |
array of LocalizedMediaImage |
Sì | Immagini artwork 16:9, una voce per lingua (vedi LocalizedMediaImage). Deve contenere almeno un'immagine. Fornisci la sorgente più grande disponibile; sono consigliati 1920 x 1080 pixel. |
localized_provider_playback_uris |
array of LocalizedProviderPlaybackUri |
Sì | Deep link per piattaforma e per lingua (vedi LocalizedProviderPlaybackUri). Almeno una voce deve elencare PLATFORM_ANDROID_TV. uri può rimandare alla pagina del programma o a un episodio. |
first_episode_air_date |
Date |
Sì | Data di messa in onda della prima puntata (vedi Date). |
external_entity_ids |
array of ExternalEntityId |
No | Identificatori di cataloghi esterni per la corrispondenza delle entità (vedi ExternalEntityId). Al massimo una voce per tipo di identificatore. |
season_count |
integer (int32) |
No | Numero di stagioni disponibili sul tuo servizio. |
content_ratings |
array of ContentRating |
No | Classificazioni dei contenuti ufficiali (vedi ContentRating). |
LiveTvProgramCandidate
L'oggetto LiveTvProgramCandidate rappresenta una trasmissione TV in diretta o un evento in streaming programmato. La finestra di trasmissione fa parte del candidato ed è separata
da availability_intervals del candidato principale, che controlla quando la
scheda può essere mostrata.
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
title |
LocalizedString |
Sì | Titolo del programma TV in diretta (vedi LocalizedString). Ogni valore è compreso tra 1 e 100 punti di codice Unicode e viene mostrato così come viene inviato. |
description |
LocalizedString |
Sì | Breve descrizione del programma TV in diretta (vedi LocalizedString). Ogni valore è compreso tra 1 e 400 punti di codice Unicode. |
localized_media_images |
array of LocalizedMediaImage |
Sì | Immagini di artwork 16:9, una voce per lingua (vedi LocalizedMediaImage). Deve contenere almeno un'immagine. Fornisci la sorgente più grande disponibile; sono consigliati 1920 x 1080 pixel. |
localized_provider_playback_uris |
array of LocalizedProviderPlaybackUri |
Sì | Deep link per piattaforma e per lingua (vedi LocalizedProviderPlaybackUri). Almeno una voce deve elencare PLATFORM_ANDROID_TV. |
broadcast_interval |
Interval |
Sì | Inizio e fine della trasmissione del programma (vedi Interval). start_time e end_time sono entrambi obbligatori. |
external_entity_ids |
array of ExternalEntityId |
No | Identificatori di cataloghi esterni per la corrispondenza delle entità (vedi ExternalEntityId). Al massimo una voce per tipo di identificatore. |
content_ratings |
array of ContentRating |
No | Classificazioni dei contenuti ufficiali (vedi ContentRating). |
Schemi di supporto
I payload candidati fanno riferimento ai seguenti oggetti condivisi per testo localizzato, deep link, artwork, identificatori esterni, motivi dei consigli, intervalli di visualizzazione, classificazioni dei contenuti e tipi di data e ora noti.
LocalizedString
L'oggetto LocalizedString contiene lo stesso testo in una o più lingue.
Ogni valore è taggato con la relativa lingua in modo che i dispositivi Google TV e Android TV possano mostrare il testo corrispondente alla lingua del dispositivo TV dell'utente:
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
values |
array of LocalizedText |
Sì | Il testo in ogni lingua che fornisci (vedi LocalizedText). Deve contenere almeno un valore. |
LocalizedText
L'oggetto LocalizedText è un testo in una singola lingua:
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
text |
string |
Sì | Il testo nella lingua specificata da language_code. |
language_code |
string |
Sì | Codice lingua BCP-47 di text, ad esempio "en-US" o "sr-Latn". |
LocalizedMediaImage
L'oggetto LocalizedMediaImage associa un'immagine alla lingua di qualsiasi testo
nell'immagine:
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
language_code |
string |
Sì | Codice lingua BCP-47 del testo nell'immagine, ad esempio "en-US" o "sr-Latn". |
image |
MediaImage |
Sì | Un'immagine in formato 16:9 (vedi MediaImage). Fornisci l'immagine di origine più grande disponibile; le dimensioni consigliate sono 1920 x 1080 pixel. |
LocalizedProviderPlaybackUri
L'oggetto LocalizedProviderPlaybackUri associa un deep link alla lingua dei contenuti che apre e all'app che lo apre:
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
playback_uri |
PlaybackUri |
Sì | Il deep link e le piattaforme a cui si applica (vedi PlaybackUri). |
language_code |
string |
Sì | Codice lingua BCP-47 dei contenuti aperti dal deep link, ad esempio "en-US" o "sr-Latn". |
package_name |
string |
Sì | Nome del pacchetto dell'applicazione Android utilizzato per aprire il deep link (ad esempio, "com.example.tvapp"). |
PlaybackUri
L'oggetto PlaybackUri definisce un deep link e le relative piattaforme di destinazione:
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
uri |
string |
Sì | URI del deep link che avvia la riproduzione del candidato nella tua app. |
platforms |
array of string (enum) |
Sì | Piattaforme a cui si applica questo deep link. Valori consentiti: PLATFORM_UNSPECIFIED, PLATFORM_ANDROID_TV, PLATFORM_ANDROID, PLATFORM_IOS. Includi PLATFORM_ANDROID_TV per i dispositivi Google TV e Android TV. |
MediaImage
L'oggetto MediaImage specifica un URL immagine, le sue dimensioni in pixel e il testo di accessibilità:
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
url |
string |
Sì | URL HTTPS dell'immagine accessibile pubblicamente. |
width |
integer |
Sì | Larghezza dell'immagine non modificata (massima) in pixel. |
height |
integer |
Sì | Altezza dell'immagine non modificata (massima) in pixel. |
accessibility_text |
string |
Sì | Testo di accessibilità (alt) che descrive l'immagine. |
ExternalEntityId
L'oggetto ExternalEntityId mappa un candidato a un identificatore in un catalogo esterno. Imposta esattamente uno dei seguenti campi per voce e includi al massimo una voce per tipo di identificatore nell'elenco external_entity_ids di un candidato:
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
tms_root_id |
string |
Una tra | ID radice TMS Gracenote. Identifica un titolo: un film, un programma o una puntata. |
tms_id |
string |
Una tra | ID variante Gracenote TMS. Identifica un'edizione o un elenco di trasmissioni. |
data_feed_element_id |
string |
Una tra | ID entità del feed di dati di Azioni multimediali. Questo valore non è correlato al segmento {recommendationsFeed} del nome della risorsa. |
RecommendationContext
L'oggetto RecommendationContext spiega perché un candidato viene consigliato e per quanto tempo si applica questa spiegazione:
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
recommendation_reason |
RecommendationReason |
No | Il motivo per cui il candidato è consigliato (vedi RecommendationReason). |
validity_interval |
Interval |
No | Finestra temporale durante la quale si applica questo contesto (vedi Interval). Ad esempio, un candidato è nuovo solo per un numero limitato di giorni. Se non viene impostato, il contesto viene applicato per tutto il tempo in cui il candidato viene archiviato. |
RecommendationReason
L'oggetto RecommendationReason contiene un motivo. Imposta esattamente uno dei seguenti campi:
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
top_on_partner |
object |
Una tra | Il candidato è un elemento con ranking elevato nel tuo servizio. Contiene un singolo campo di numero intero positivo rank (ad esempio, {"rank": 1} per "Top 1 on Partner"). |
popular_on_partner |
object |
Una tra | Il candidato è popolare sul tuo servizio. Passa un oggetto vuoto ({}). |
new_on_partner |
object |
Una tra | Il candidato è nuovo nel tuo servizio. Passa un oggetto vuoto ({}). |
generic |
object |
Una tra | Un motivo personalizzato. Contiene un singolo campo LocalizedString generic_reason (vedi LocalizedString). Ogni valore è compreso tra 1 e 100 punti di codice Unicode. |
ContentRating
L'oggetto ContentRating rappresenta una classificazione dei contenuti ufficiale assegnata da un'agenzia di classificazione:
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
rating_system |
string |
Sì | Agenzia o sistema di classificazione, ad esempio "MPAA", "BBFC" o "CBFC". |
rating_value |
string |
Sì | Valutazione definita da rating_system, ad esempio "PG-13" o "U/A 13+". |
Timestamp
Un Timestamp viene codificato in JSON come stringa RFC 3339 in UTC con un suffisso Z, ad esempio "2026-10-01T18:00:00Z". Sono consentite le frazioni di secondo, ad esempio "2026-10-01T18:00:00.500Z".
Duration
Un Duration è codificato in JSON come stringa che contiene il numero di secondi seguito dal suffisso s, ad esempio "7200s" per 2 ore. Sono consentite frazioni di secondo, ad esempio "5400.5s".
Date
Un Date è una data di calendario senza fuso orario. È codificato in JSON come oggetto con i seguenti campi:
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
year |
integer |
Sì | L'anno della data, ad esempio 2025. |
month |
integer |
No | Mese dell'anno, da 1 a 12. Imposta su 0 o ometti se il mese non è noto. |
day |
integer |
No | Giorno del mese, da 1 a 31, valido per l'anno e il mese specificati. Imposta su 0 o ometti se il giorno non è noto. Richiede month. |
Ad esempio, {"year": 2025, "month": 1, "day": 17} rappresenta il 17 gennaio 2025, {"year": 2025, "month": 1} rappresenta gennaio 2025 con un giorno sconosciuto e {"year": 2025} rappresenta una data nel 2025 con un mese e un giorno sconosciuti.
Interval
Un Interval è una finestra temporale semiaperta che inizia alle ore start_time
(inclusa) e termina alle ore end_time (esclusa). Un orario T è compreso nell'intervallo quando start_time <= T e T < end_time.
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
start_time |
string (Timestamp) |
Sì | Inizio inclusivo della finestra (vedi Timestamp), ad esempio "2026-10-01T18:00:00Z". |
end_time |
string (Timestamp) |
Sì | Fine esclusiva della finestra (vedi Timestamp), ad esempio "2026-10-01T21:00:00Z". Deve essere successiva a start_time. |
Esempio di richiesta
L'esempio seguente sostituisce i candidati del feed in-en-cricket del partner example-partner con tre candidati (un film, un programma TV e un programma TV in diretta). Il filmato contiene il testo in due lingue:
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"
}
]
}
]
}'
Comportamento di risposta e sostituzione
Questa sezione descrive la risposta HTTP restituita da replaceCandidates e
il modo in cui ogni chiamata aggiorna i candidati archiviati.
ReplaceCandidatesResponse
Se la richiesta ha esito positivo, l'API restituisce HTTP 200 OK con un corpo ReplaceCandidatesResponse:
| Campo | Tipo | Descrizione |
|---|---|---|
replaced_candidates_count |
integer (int32) |
Numero di candidati sostituiti. |
Per la richiesta di esempio precedente, la risposta è:
{
"replaced_candidates_count": 3
}
Comportamento di sostituzione
Comprendere in che modo replaceCandidates aggiorna i candidati archiviati è essenziale per progettare l'integrazione:
- Sostituzione completa per feed. Ogni chiamata sostituisce completamente l'elenco di candidati memorizzato in precedenza per il feed denominato nel percorso dell'URL. Invia sempre l'insieme completo di candidati attivi per quel feed.
- Gli altri feed rimangono invariati. I feed a cui non invii candidati rimangono invariati finché non lo fai. Ad esempio, la sostituzione dei candidati di un feed non modifica i candidati memorizzati per un altro feed e la sostituzione dei candidati di
{recommendationsFeed}-stagingnon modifica{recommendationsFeed}. - Una chiamata per feed. Per aggiornare più feed, effettua una chiamata per feed. Le chiamate sono indipendenti: se una non va a buon fine, gli altri feed mantengono i nuovi candidati e riprovi solo la chiamata non riuscita.
- Invia nuovamente i feed attivi almeno ogni 30 giorni. Anche se il catalogo di un feed non è cambiato, invia nuovamente ogni feed attivo almeno una volta ogni 30 giorni (o secondo una pianificazione giornaliera o settimanale regolare con jitter randomizzato) in modo che i candidati rimangano attivi e non scadano. L'impostazione di un
availability_intervalsend_timemolto lontano nel futuro non sostituisce l'invio periodico. - Esecuzione atomica. L'API applica la richiesta in modo atomico. Se un candidato non supera la convalida, l'API rifiuta l'intera richiesta e il feed mantiene i candidati precedenti.