Integrar o recurso "Continuar assistindo" usando a API REST

O SDK do Engage oferece uma API REST para proporcionar uma experiência consistente de continuar assistindo em plataformas que não são Android, como iOS e Roku TV. A API permite que os desenvolvedores atualizem o status "Continuar assistindo" para usuários que aceitaram o recurso em plataformas que não são Android.

Pré-requisitos

  • Primeiro, você precisa concluir a integração no dispositivo baseada no SDK Engage. Essa etapa essencial estabelece a associação necessária entre o ID do usuário do Google e o AccountProfile do seu app.
  • Acesso e autenticação da API: para visualizar e ativar a API no seu projeto do Google Cloud, é necessário passar por um processo de lista de permissões. Todas as solicitações de API exigem autenticação.

Quero acessar

Para acessar e ativar a API no console do Google Cloud, sua conta precisa estar inscrita.

  1. O ID de cliente do Google Workspace precisa estar disponível. Se não estiver disponível, talvez seja necessário configurar um Google Workspace e as Contas do Google que você quer usar para chamar a API.
  2. Configure uma conta no console do Google Cloud usando um e-mail associado ao Google Workspace.
  3. Criar um novo projeto.
  4. Crie uma conta de serviço para autenticação de API. Depois de criar a conta de serviço, você terá dois itens:
    • Um ID de conta de serviço.
    • Um arquivo JSON com a chave da conta de serviço. Mantenha esse arquivo seguro. Você vai precisar dela para autenticar o cliente na API mais tarde.
  5. O Workspace e as Contas do Google associadas agora podem usar APIs REST. Depois que a mudança for propagada, você vai receber uma notificação informando se a API está pronta para ser chamada pelas suas contas de serviço.
  6. Siga estas etapas para se preparar para fazer uma chamada de API delegada.

Publicar cluster de continuação

Para publicar os dados do Engage, faça uma solicitação POST para a API publishContinuationCluster usando a sintaxe a seguir.

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

Em que:

  • package_name: o nome do pacote do provedor de mídia.
  • accountId: o ID exclusivo da conta do usuário no seu sistema. Ele precisa corresponder ao accountId usado no caminho no dispositivo.
  • profileId: o ID exclusivo do perfil do usuário na conta do seu sistema. Ele precisa corresponder ao profileId usado no caminho no dispositivo.

O URL da conta sem perfil é:

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

O payload da solicitação é representado no campo entities. entities representa uma lista de entidades de conteúdo, que pode consistir em um ou mais dos seguintes: MovieEntity, TVEpisodeEntity, LiveStreamingVideoEntity ou VideoClipEntity. Este campo é obrigatório.

Corpo da solicitação

Campo

Tipo

Obrigatório

Descrição

entities

Lista de objetos MediaEntity

Sim

Lista de entidades de conteúdo com no máximo cinco itens. Somente os cinco primeiros serão retidos, e o restante será descartado. Uma lista vazia é permitida para indicar que o usuário terminou de assistir todas as entidades.

O campo entities contém movieEntity, tvEpisodeEntity, liveStreamingVideoEntity e videoClipEntity individuais.

Campo

Tipo

Descrição

movieEntity

MovieEntity

Um objeto que representa um filme no ContinuationCluster.

tvEpisodeEntity

TvEpisodeEntity

Um objeto que representa um episódio de TV no ContinuationCluster.

liveStreamingVideoEntity

LiveStreamingVideoEntity

Um objeto que representa um streaming de vídeo ao vivo no ContinuationCluster.

videoClipEntity

VideoClipEntity

Um objeto que representa um clipe de vídeo no ContinuationCluster.

Cada objeto na matriz de entidades precisa ser um dos tipos de MediaEntity disponíveis, ou seja, MovieEntity, TvEpisodeEntity, LiveStreamingVideoEntity ou VideoClipEntity, além de campos comuns e específicos do tipo.

O snippet de código a seguir mostra o payload do corpo da solicitação para a 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"
        }
      }
    }
  ]
}

Excluir os dados do Engage

Use a API clearCluster para remover os dados do Engage.

Para excluir os dados do cluster de continuação, faça uma solicitação POST para a API clearCluster usando a sintaxe a seguir.

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

Em que:

  • package_name: o nome do pacote do provedor de mídia.
  • accountId: o ID exclusivo da conta do usuário no seu sistema. Ele precisa corresponder ao accountId usado no caminho no dispositivo.
  • profileId: o ID exclusivo do perfil do usuário na conta do seu sistema. Ele precisa corresponder ao profileId usado no caminho no dispositivo.

O URL da conta sem perfil é:

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

O payload da API clearCluster contém apenas um campo, reason, que contém um DeleteReason que especifica o motivo da remoção de dados.

{
  "reason": "DELETE_REASON_LOSS_OF_CONSENT"
}

Teste

Depois de postar os dados, use uma conta de teste de usuário para verificar se o conteúdo esperado aparece na linha "Continuar assistindo" nas plataformas de destino do Google, como o Google TV e os apps para dispositivos móveis do Google TV para Android e iOS.

Durante os testes, permita um atraso de propagação razoável de alguns minutos e siga os requisitos de exibição, como assistir parte de um filme ou terminar um episódio. Consulte as diretrizes do recurso Assistir a seguir para desenvolvedores de apps para mais detalhes.