Integra i suggerimenti utilizzando l'API REST

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:

  1. Crea un account Google Workspace. Segui le istruzioni riportate nella pagina di assistenza Google Workspace per configurare un account per la tua organizzazione.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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: Bearer in 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}-staging non 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_intervals end_time molto 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.