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 for bem-sucedido, você vai ver uma saída semelhante a esta:

    {
"stream_id": "8d2b2292-6356-4c0e-94be-cece01d2df2e: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 o polling dos metadados de anúncios, faça o seguinte:

  1. Leia o valor metadata_url da resposta de registro de stream.

  2. Faça uma solicitação GET para o endpoint. Para mais detalhes, consulte Método: metadata.

    O exemplo a seguir busca metadados de anúncios:

    const response = await fetch(metadata_url);
console.log(await response.json());

    Se a solicitação for bem-sucedida, você vai receber a resposta PodMetadata para os intervalos publicitários atuais e futuros:

    {
  "tags":{
    "google_5555555555":{
      "ad":"0000229834_ad1",
      "ad_break_id":"0000229834",
      "type":"firstquartile"
    },
    "google_1234567890123456789":{
      "ad":"0000229834_ad1",
      "ad_break_id":"0000229834",
      "type":"progress"
    },
    ...
  },
  "ads":{
    "0000229834_ad1":{
      "ad_break_id":"0000229834",
      "position":1,
      "duration":15,
      "clickthrough_url":"https://.../",
      ...
    },
          ...
  },
  "ad_breaks":{
    "0000229834":{
      "type":"mid",
      "duration":15,
      "ads":1
    },
    ...
  }
}

  3. Salve o objeto tags para as etapas posteriores.

  4. Defina um timer usando o valor polling_frequency para solicitar regularmente metadados de todos os intervalos de publicidade sucessivos.

Carregue 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 mais 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 data/hora.

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_1234567890123456789",
  ...
}

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

    TXXXgoogle_1234567890123456789

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 do 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.

  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. 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 completo de verificação de mídia 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_5555555555123456789`;

const response = await fetch(completeUrl);

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

Use o monitoramento de 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.