Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Integrare la funzionalità Continua a guardare utilizzando l'API REST

L'SDK Engage offre un'API REST per fornire un'esperienza di continuazione della visione coerente su piattaforme non Android come iOS e Roku TV. L'API consente agli sviluppatori di aggiornare lo stato "Continua a guardare" per gli utenti che hanno eseguito l'opt-in da piattaforme non Android.

Prerequisiti

Devi prima completare l'integrazione on-device basata sull'SDK Engage. Questo passaggio fondamentale stabilisce l'associazione necessaria tra l'ID utente di Google e il AccountProfile della tua app.
Accesso e autenticazione all'API: per visualizzare e abilitare l'API nel tuo progetto Google Cloud, devi seguire una procedura di inserimento nella lista consentita. Tutte le richieste API richiedono l'autenticazione.

Ottieni accesso

Per ottenere l'accesso per visualizzare e abilitare l'API nella console Google Cloud, il tuo account deve essere registrato.

L'ID cliente Google Workspace deve essere disponibile. Se non è disponibile, potresti dover configurare un account Google Workspace e tutti gli Account Google che vuoi utilizzare per chiamare l'API.
Configura un account con la console Google Cloud utilizzando un indirizzo email associato a Google Workspace.
Crea un nuovo progetto.
Crea un service account per l'autenticazione API. Una volta creato il service account, avrai due elementi:
- Un ID service account.
- Un file JSON con la chiave del service account. Mantieni questo file sicuro. Ti servirà per autenticare il client nell'API in un secondo momento.
Workspace e gli Account Google associati ora possono utilizzare le API REST. Una volta propagata la modifica, riceverai una notifica che ti informerà se l'API è pronta per essere chiamata dai tuoi service account.
Segui questi passaggi per prepararti a effettuare una chiamata API delegata.

Pubblica cluster di continuazione

Per pubblicare i dati di Engage, esegui una richiesta POST all'API publishContinuationCluster utilizzando la seguente sintassi.

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/profiles/{profile_id}/publishContinuationCluster

Dove:

package_name: il nome del pacchetto del fornitore di contenuti multimediali
accountId: l'ID univoco dell'account utente nel tuo sistema. Deve corrispondere alla accountId utilizzata nel percorso on-device.
profileId: l'ID univoco del profilo dell'utente all'interno dell'account nel tuo sistema. Deve corrispondere al profileId utilizzato nel percorso on-device.

L'URL dell'account senza profilo è:

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/publishContinuationCluster

Il payload della richiesta è rappresentato nel campo entities. entities rappresenta un elenco di entità di contenuti, che possono essere costituite da uno o più dei seguenti elementi: MovieEntity, TVEpisodeEntity, LiveStreamingVideoEntity o VideoClipEntity. Questo campo è obbligatorio.

Corpo della richiesta

Campo	Tipo	Obbligatorio	Descrizione
entità	Elenco di oggetti MediaEntity	Sì	Elenco di entità di contenuti con un massimo di 5. Verranno conservati solo i primi cinque e gli altri verranno eliminati. È consentito un elenco vuoto per indicare che l'utente ha finito di guardare tutte le entità.

Il campo entities contiene i singoli movieEntity, tvEpisodeEntity, liveStreamingVideoEntity e videoClipEntity.

Campo	Tipo	Descrizione
movieEntity	MovieEntity	Un oggetto che rappresenta un film all'interno di ContinuationCluster.
tvEpisodeEntity	TvEpisodeEntity	Un oggetto che rappresenta una puntata TV all'interno di ContinuationCluster.
liveStreamingVideoEntity	LiveStreamingVideoEntity	Un oggetto che rappresenta un video in live streaming all'interno di ContinuationCluster.
videoClipEntity	VideoClipEntity	Un oggetto che rappresenta un video clip all'interno di ContinuationCluster.

Ogni oggetto nell'array entities deve essere uno dei tipi MediaEntity disponibili, ovvero MovieEntity, TvEpisodeEntity, LiveStreamingVideoEntity o VideoClipEntity, insieme ai campi comuni e specifici del tipo.

Il seguente snippet di codice mostra il payload del corpo della richiesta per l'API publishContinuationCluster.

{
  "entities": [
    {
      "movieEntity": {
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "name": "Movie1",
        "platform_specific_playback_uris": [
        {
          "uri": "https://www.example.com/movie_entity_uri_for_android",
          "platforms": [
            "PLATFORM_ANDROID_TV",
            "PLATFORM_ANDROID"
          ]
        },
        {
          "uri": "https://www.example.com/movie_entity_uri_for_iOS",
          "platforms": [
            "PLATFORM_IOS"
          ]
        }
        ],
        "poster_images": [
          {
            "url": "http://www.example.com/movie1_img1.png",
            "width": 1920,
            "height": 1080,
            "accessibility_text": "Movie 1 HD poster"
          },
          {
            "url": "http://www.example.com/movie1_imag2.png",
            "width": 640,
            "height": 360,
            "accessibility_text": "Movie 1 SD poster"
          }
        ],
        "last_engagement_time_millis": 864600000,
        "duration_millis": 5400000,
        "last_play_back_position_time_millis": 3241111
      }
    },
    {
      "tvEpisodeEntity": {
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "name": "TV SERIES EPISODE 1",
        "platform_specific_playback_uris": [
        {
          "uri": "https://www.example.com/episode_entity_uri_for_android_mobile",
          "platforms": [
            "PLATFORM_ANDROID"
          ]
        },
        {
          "uri": "https://www.example.com/episode_entity_uri_for_android_tv",
          "platforms": [
            "PLATFORM_ANDROID_TV"
          ]
        },
        {
          "uri": "https://www.example.com/episode_entity_uri_for_iOS",
          "platforms": [
            "PLATFORM_IOS"
          ]
        }
        ],
        "poster_images": [
          {
            "url": "http://www.example.com/episode1_img1.png",
            "width": 1920,
            "height": 1080,
            "accessibility_text": "Episode 1 HD poster"
          },
          {
            "url": "http://www.example.com/episode1_imag2.png",
            "width": 640,
            "height": 360,
            "accessibility_text": "Episode 1 SD poster"
          }
        ],
        "last_engagement_time_millis": 864600000,
        "duration_millis": 1800000,
        "last_play_back_position_time_millis": 2141231,
        "episode_display_number": "1",
        "season_number": "1",
        "show_title": "title"
      }
    },
    {
      "liveStreamingVideoEntity": {
        "name": "Live Sports Championship",
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "last_engagement_time_millis": 1780978284000,
        "last_play_back_position_time_millis": 1800000,
        "duration_millis": 7200000,
        "platform_specific_playback_uris": [
          {
            "uri": "https://www.example.com/live_streaming_entity_uri_for_android_tv",
            "platforms": ["PLATFORM_ANDROID_TV"]
          }
        ],
        "poster_images": [
          {
            "url": "http://www.example.com/live_stream_image1.png",
            "width": 1920,
            "height": 1080,
            "accessibility_text": "Live Sports Championship Cover Image"
          }
        ],
        "start_time_epoch_millis": 1780976484000,
        "broadcaster": "Global Sports Network",
        "broadcaster_icon": {
          "url": "https://www.example.com/gsports.jpg",
          "width": 512,
          "height": 512,
          "accessibility_text": "Global Sports Network Logo"
        }
      }
    },
    {
      "videoClipEntity": {
        "name": "How to Brew the Perfect Espresso",
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "last_engagement_time_millis": 1780978284000,
        "last_play_back_position_time_millis": 120000,
        "duration_millis": 600000,
        "platform_specific_playback_uris": [
          {
            "uri": "https://www.example.com/video_clip_entity_uri_for_android_tv",
            "platforms": ["PLATFORM_ANDROID_TV"]
          }
        ],
        "poster_images": [
          {
            "url": "http://www.example.com/video_clip_image1.png",
            "width": 1920,
            "height": 1080,
            "accessibility_text": "Espresso Tutorial Cover Image"
          }
        ],
        "created_time_epoch_millis": 1780900000000,
        "creator": "Coffee Enthusiast John",
        "creator_image": {
          "url": "https://www.example.com/image/thumb/creators/john_avatar.jpg",
          "width": 256,
          "height": 256,
          "accessibility_text": "John's Avatar"
        }
      }
    }
  ]
}

Elimina i dati di Engage

Utilizza l'API clearCluster per rimuovere i dati di Engage.

Per eliminare i dati del cluster di continuazione, esegui una richiesta POST all'API clearCluster utilizzando la seguente sintassi.

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/profiles/{profile_id}/clearCluster

Dove:

package_name: il nome del pacchetto del fornitore di contenuti multimediali.
accountId: l'ID univoco dell'account utente nel tuo sistema. Deve corrispondere alla accountId utilizzata nel percorso on-device.
profileId: l'ID univoco del profilo dell'utente all'interno dell'account nel tuo sistema. Deve corrispondere al profileId utilizzato nel percorso on-device.

L'URL dell'account senza profilo è:

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/clearCluster

Il payload per l'API clearCluster contiene un solo campo, reason, che contiene un DeleteReason che specifica il motivo della rimozione dei dati.

{
  "reason": "DELETE_REASON_LOSS_OF_CONSENT"
}

Test

Dopo aver pubblicato i dati, utilizza un account di test utente per verificare che i contenuti previsti vengano visualizzati nella riga Continua a guardare sulle piattaforme Google di destinazione, come Google TV e le app mobile Google TV per Android e iOS.

Durante i test, concedi un ritardo di propagazione ragionevole di alcuni minuti e rispetta i requisiti di visualizzazione, ad esempio guardare parte di un film o terminare un episodio. Per maggiori dettagli, consulta le linee guida di Cosa guardare per gli sviluppatori di app.