Preparar o cliente para o redirecionamento de veiculação de conjunto

Este guia aborda o desenvolvimento de um aplicativo cliente para carregar uma transmissão ao vivo HLS ou DASH com a API Pod Serving e seu manipulador de manifesto.

Pré-requisitos

Antes de continuar, você precisa ter o seguinte:

Fazer uma solicitação de stream

Quando o usuário selecionar uma transmissão, faça o seguinte:

  1. Faça uma solicitação POST ao método do serviço de transmissão ao vivo. Para mais detalhes, consulte Método: stream.

  2. Transmita parâmetros de segmentação de anúncios nos formatos application/x-www-form-urlencoded ou application/json. Essa solicitação registra uma sessão de stream com a DAI do Google.

    O exemplo a seguir faz uma solicitação de stream:

    Codificação de formulário

    const url = `https://dai.google.com/ssai/pods/api/v1/` +
      `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`;

const params = new URLSearchParams({
        cust_params: 'section=sports&page=golf,tennis'
}).toString();

const response = await fetch(url, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded'
        },
        body: params
});

console.log(await response.json());

    Codificação JSON

    const url = `https://dai.google.com/ssai/pods/api/v1/` +
      `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`;

const response = await fetch(url, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          cust_params: {
            section: 'sports',
            page: 'golf,tennis'
          }
        })
});

console.log(await response.json());

    Se a operação for bem-sucedida, você vai ver uma saída semelhante a esta:

    {
"stream_id": "c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS",
"media_verification_url": "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/",
"metadata_url": "https://dai.google.com/linear/pods/hls/.../metadata",
"session_update_url": "https://dai.google.com/linear/.../session",
"polling_frequency": 10
}

  3. Na resposta JSON, localize o ID da sessão de transmissão e armazene outros dados para etapas subsequentes.

Pesquisar metadados de anúncios

Para fazer uma pesquisa de metadados de anúncios, faça o seguinte:

  1. Leia o valor metadata_url da resposta de registro do fluxo.

  2. Faça uma solicitação GET inicial para o endpoint metadata_url.

    • Omita o parâmetro de consulta delta_token. Esse processo permite que o servidor retorne os metadados completos da janela do gravador de vídeo digital (DVR) da transmissão. A janela de DVR contém o período da transmissão disponível para um espectador voltar e reproduzir. A resposta inclui um campo next_delta_token.

  3. Para otimizar a largura de banda, armazene o valor next_delta_token da resposta mais recente.

  4. Na próxima solicitação, envie esse valor como o parâmetro de consulta delta_token. O servidor retorna apenas os metadados que mudaram desde que o token foi gerado. Sempre envie o token mais recente que você recebeu. Não tente analisar, modificar ou construir o token. Para mais detalhes, consulte Método: metadata.

    O exemplo a seguir busca metadados de anúncios:

    // Initial request (returns full metadata and next_delta_token)
let response = await fetch(metadata_url);
let metadata = await response.json();
let deltaToken = metadata.next_delta_token;

// Subsequent request (returns only changes since deltaToken)
if (deltaToken) {
  const url = new URL(metadata_url);
  url.searchParams.append('delta_token', deltaToken);
  response = await fetch(url.toString());
  const deltaMetadata = await response.json();
  // Merge deltaMetadata into your local cache
  mergeMetadata(metadata, deltaMetadata);
  deltaToken = deltaMetadata.next_delta_token;
}

    Se for bem-sucedido, você vai receber a resposta PodMetadata. Se você fornecer o parâmetro delta_token, a resposta vai conter apenas os anúncios, os intervalos publicitários e as tags que o servidor adicionou ou atualizou desde que o token foi gerado. A resposta também contém um novo valor next_delta_token. Se algum intervalo de anúncio estiver desatualizado, a resposta também vai incluir uma lista obsolete_ad_break_ids dos intervalos a serem removidos do cache.

    {
  "next_delta_token": "eyJyYW5nZXMiOlt7InMiOjEsImUiOjN9XX0",
  "obsolete_ad_break_ids": ["0003069407"],
  "tags":{
    "google_1022389921":{
      "ad":"0003069408_ad1",
      "ad_break_id":"0003069408",
      "type":"start"
    },
    ...
  },
  "ads":{
    "0003069408_ad1":{
      "ad_break_id":"0003069408",
      "position":1,
      "duration":10.01,
      "title":"External - Pod Midroll 1",
      "clickthrough_url":"https://.../",
      ...
    },
    ...
  },
  "ad_breaks":{
    "0003069408":{
      "type":"mid",
      "duration":30,
      "ads":3
    },
    ...
  }
}

  5. Salve o objeto tags e mescle as atualizações no cache local. Se o parâmetro obsolete_ad_break_ids estiver presente, remova esses intervalos de anúncio e os anúncios e tags associados do cache.

  6. Defina um timer usando o valor polling_frequency para solicitar metadados regularmente. Em cada pesquisa, envie o valor next_delta_token retornado na resposta de metadados mais recente como o parâmetro de consulta delta_token.

Carregar a transmissão no player de vídeo

Depois de receber o ID da sessão da resposta de registro, transmita o ID para o manipulador de manifesto ou crie um URL de manifesto para carregar o stream em um player de vídeo.

Para transmitir o ID da sessão, consulte a documentação do manipulador de manifesto. Se você desenvolver um manipulador de manifesto, consulte Manipulador de manifesto para transmissão ao vivo.

O exemplo a seguir monta um URL de manifesto:

https://<your_manifest_manipulator_url>/manifest.m3u8?DAI_stream_ID=SESSION_ID&network_code=NETWORK_CODE&DAI_custom_asset_key=CUSTOM_ASSET_KEY"

Quando o player estiver pronto, comece a reprodução.

Detectar eventos de anúncios

Verifique o formato do contêiner da sua transmissão para os metadados com carimbo de data/hora:

  • As transmissões HLS com contêineres Transport Stream (TS) usam tags ID3 com carimbo de data/hora para transportar metadados com carimbo de data/hora. Para mais detalhes, consulte Sobre o formato de aplicativo de mídia comum com HTTP Live Streaming (HLS).

  • Os fluxos DASH usam elementos EventStream para especificar eventos no manifesto.

  • As transmissões DASH usam elementos InbandEventStream quando os segmentos contêm caixas de mensagem de evento (emsg) para dados de payload, incluindo tags ID3. Para detalhes, consulte InbandEventStream.

  • Os streams CMAF, incluindo DASH e HLS, usam caixas emsg que contêm tags ID3.

Para recuperar tags ID3 do seu stream, consulte o guia do player de vídeo. Para mais detalhes, consulte o guia de como processar metadados com carimbo de tempo.

Para recuperar o ID do evento de anúncio das tags ID3, faça o seguinte:

  1. Filtre os eventos por scheme_id_uri com urn:google:dai:2018 ou https://aomedia.org/emsg/ID3.

  2. Extraia a matriz de bytes do campo message_data.

    O exemplo a seguir decodifica os dados emsg em JSON:

    {
  "scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
  "presentation_time": 27554,
  "timescale": 1000,
  "message_data": "ID3TXXXgoogle_1022389921",
  ...
}

  3. Filtre as tags ID3 com o formato TXXXgoogle_{ad_event_ID}:

    TXXXgoogle_1022389921

Mostrar dados de eventos de anúncios

Para encontrar o objeto TagSegment, faça o seguinte:

  1. Recupere o objeto de metadados do anúncio tags de Pesquisar metadados de anúncio. O objeto tags é uma matriz de objetos TagSegment.

  2. Use o ID completo do evento de anúncio para encontrar um objeto TagSegment com o tipo progress.

  3. Use os primeiros 17 caracteres do ID do evento de anúncio para encontrar um objeto TagSegment de outros tipos.

    Como o app cliente pesquisa os metadados de anúncios periodicamente, pode ocorrer um atraso entre o momento em que o player de vídeo encontra uma tag ID3 no stream e quando os metadados associados ficam disponíveis. Se o app cliente não encontrar uma tag ID3 nas tags armazenadas, mantenha a tag em uma fila e reprocesse após a próxima pesquisa de metadados. Mantenha a tag na fila até que o processamento seja concluído.

  4. Depois de ter o TagSegment, use a propriedade ad_break_id como chave para encontrar o objeto AdBreak no objeto ad_breaks de metadados do anúncio.

    O exemplo a seguir encontra um objeto AdBreak:

    {
  "type":"mid",
  "duration":15,
  "ads":1
}

  5. Use os dados TagSegment e AdBreak para mostrar informações sobre a posição do anúncio no intervalo de anúncio. Por exemplo, Ad 1 of 3.

Enviar pings de verificação de mídia

Para cada evento de anúncio, exceto o tipo progress, envie um ping de verificação de mídia. A DAI do Google descarta eventos progress, e o envio frequente deles pode afetar o desempenho do app.

Para gerar o URL de verificação de mídia completo de um evento de anúncio, faça o seguinte:

  1. Na resposta do fluxo, adicione o ID do evento de anúncio completo ao valor media_verification_url.

  2. Faça uma solicitação GET com o URL completo:

    // media_verification_url: "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/"
const completeUrl = `${media_verification_url}google_1022389921`;

const response = await fetch(completeUrl);

    Se a solicitação for bem-sucedida, você vai receber uma resposta com o código de status 202. Caso contrário, você receberá um código de erro 404.

Use o Monitoramento da atividade de streaming (SAM) para inspecionar um registro histórico de todos os eventos de anúncio. Para mais detalhes, consulte Monitorar e resolver problemas de uma transmissão ao vivo.