Inserir anúncios com metadados de tempo de agrupamento de anúncios

Este guia descreve como inserir intervalos de anúncio usando o método de metadados de tempo do conjunto de anúncios (ATM, na sigla em inglês) para buscar o tempo e a duração exatos dos intervalos de anúncio, incluindo anúncios precedentes.

Para inserir anúncios precedentes e gerenciar o retorno ao conteúdo após intervalos de anúncio intermediários, recomendamos chamar as seguintes APIs:

API de metadados de tempo do conjunto de anúncios (ATM): consulta os resultados da decisão do conjunto de anúncios, incluindo a duração do anúncio e da inserção.
Endpoint de segmento de anúncio: solicita segmentos de anúncio ou inserções com a opção de encerrar o conjunto de anúncios atual.

Opcionalmente, para eventos de transmissão ao vivo de alta simultaneidade, recomendamos chamar Early Ad Break Notification (EABN) API para programar decisões de anúncios antes do início do intervalo de anúncio.

Pré-requisitos

Para começar, você precisa de um evento de transmissão ao vivo configurado para o tipo de inserção de anúncios dinâmicos (DAI) Redirecionamento de veiculação de blocos. Escolha um dos seguintes métodos:

Interface do Ad Manager:configure uma transmissão ao vivo para DAI.
API do Ad Manager: use uma biblioteca de cliente (opções disponíveis) para chamar o LiveStreamEventService.createLiveStreamEvents método. Defina o parâmetro LiveStreamEvent.dynamicAdInsertionType como POD_SERVING_REDIRECT.

Recuperar o stream de conteúdo

Quando um usuário seleciona um evento de transmissão ao vivo, o app cliente faz uma solicitação de stream para o Google Ad Manager. Na resposta do stream, o app extrai o ID da sessão e os metadados da DAI do Google para incluir na solicitação de manifesto do stream.

O exemplo a seguir transmite um ID de sessão da DAI do Google para um manipulador de manifesto:

https://MANIFEST_MANIPULATOR_URL/manifest.m3u8?DAI_stream_ID=SESSION_ID&network_code=NETWORK_CODE&DAI_custom_asset_key=CUSTOM_ASSET_KEY

Ao processar a solicitação de reprodução de conteúdo de vídeo, armazene o ID da sessão da DAI do Google e CUSTOM_ASSET_KEY da solicitação para se preparar para a costura de anúncios.

Recuperar metadados de tempo do conjunto de anúncios

Para recuperar a marcação de tempo do conjunto de anúncios, siga estas etapas:

Gere um token HMAC.
Chame a API ATM com o token HMAC.

Solicitar metadados de tempo para anúncios precedentes

Verifique as configurações de anúncios precedentes para seu evento de transmissão ao vivo usando as seguintes opções:

Para recuperar os resultados da decisão de anúncios precedentes, faça uma solicitação à API ATM.

O exemplo a seguir faz uma solicitação de ATM para anúncios precedentes:

curl "https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/pod.json?stream_id=SESSION_ID&ad_break_id=preroll&auth-token=your_signed_HMAC_token"

Solicitar metadados de tempo para anúncios intermediários

Para recuperar os metadados do conjunto de anúncios para anúncios intermediários, siga estas etapas:

Analise o manifesto de transmissão ao vivo para encontrar os marcadores de anúncio que contêm o tempo e a duração de cada intervalo de anúncio intermediário.
Chame o endpoint da API ATM para solicitar a duração exata do conjunto de anúncios e da inserção. A API retorna um objeto JSON com os resultados da decisão do bloco de anúncios.

O exemplo a seguir faz uma solicitação de ATM para anúncios intermediários:

curl "https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/pod.json?stream_id=SESSION_ID&ad_break_id=AD_BREAK_ID&pd=AD_BREAK_DURATION&auth-token=your_signed_HMAC_token"

Se for bem-sucedido, você verá uma saída semelhante ao seguinte objeto JSON:

{
  "status": "final",
  "ads": [
    {
      "duration_ms": 5046,
      "variants": {
        "devrel1428000": {
          "segment_extension": "ts",
          "segment_durations": {
            "timescale": 1000,
            "values": [
              5045
            ]
          }
        },
        "devrel1928000": {
          "segment_extension": "ts",
          "segment_durations": {
            "timescale": 1000,
            "values": [
              5045
            ]
          }
        }
      }
    }
  ],
  "slate": {
    "duration_ms": 0,
    "variants": {
      "devrel1428000": {
        "segment_extension": "ts",
        "segment_durations": {
          "timescale": 1000,
          "values": [
            5005,
            ...
            5046
          ]
        }
      },
      "devrel1928000": {
        "segment_extension": "ts",
        "segment_durations": {
          "timescale": 1000,
          "values": [
            5005,
            ...
            5046
          ]
        }
      }
    }
  }
}

Costurar anúncios no manifesto de conteúdo

As seções a seguir explicam como modificar o manifesto de transmissão ao vivo e adicionar os segmentos de anúncio.

Identificar segmentos de intervalo de anúncio e inserir descontinuidades

Ao processar cada manifesto de variante, identifique as tags EXT-X-CUE-IN e EXT-X-CUE-OUT no stream, indicando o início e o fim de um intervalo de anúncio.

Substitua as tags EXT-X-CUE-IN e EXT-X-CUE-OUT pelos elementos EXT-X-DISCONTINUITY para que o player de vídeo do cliente alterne entre conteúdo e anúncios.

O exemplo de manifesto a seguir substitui as tags EXT-X-CUE-IN e EXT-X-CUE-OUT:

#EXTM3U
#EXT-X-VERSION:6
#EXT-X-TARGETDURATION:6
#EXT-X-MEDIA-SEQUENCE:0

#EXTINF:5.000,
contentorigin.com/1.ts
#EXTINF:5.000,
contentorigin.com/2.ts
#EXT-X-CUE-OUT:15.000
#EXTINF:5.000,
contentorigin.com/3.ts
#EXTINF:5.000,
contentorigin.com/4.ts
#EXTINF:5.000,
contentorigin.com/5.ts
#EXT-X-CUE-IN
#EXTINF:5.000,
contentorigin.com/6.ts
#EXTINF:5.000,
contentorigin.com/7.mp4
#EXTINF:5.000,
contentorigin.com/8.mp4

O exemplo a seguir mostra um manifesto substituído:

#EXTM3U
#EXT-X-VERSION:6
#EXT-X-TARGETDURATION:6
#EXT-X-MEDIA-SEQUENCE:0

#EXTINF:5.000,
contentorigin.com/1.ts
#EXTINF:5.000,
contentorigin.com/2.ts
#EXTINF:5.000,
#EXT-X-DISCONTINUITY
{... Insert ad segments here ...}
#EXT-X-DISCONTINUITY
#EXTINF:5.000,
contentorigin.com/6.mp4
#EXTINF:5.000,
contentorigin.com/7.mp4
#EXTINF:5.000,
contentorigin.com/8.mp4

Os segmentos de anúncio da DAI do Google não são criptografados. Se o conteúdo estiver criptografado, remova a criptografia inserindo o elemento EXT-X-KEY:METHOD=NONE antes do primeiro segmento de anúncio de cada intervalo de anúncio. No final do intervalo de anúncio, adicione a criptografia novamente inserindo um EXT-X-KEY apropriado.

Acompanhe o horário de início, a duração e o índice do próximo intervalo de anúncio futuro.

Criar URLs de segmento de anúncio

Substitua os segmentos de conteúdo entre as tags EXT-X-DISCONTINUITY por URLs de cada segmento de anúncio. Para determinar quantos segmentos de anúncio inserir, use ads.segment_durations.values fornecido na resposta JSON da API ATM.

Para encerrar um conjunto de anúncios mais cedo ao detectar uma tag EXT-X-CUE-IN, adicione o parâmetro d= ao URL do segmento de anúncio final. Esse parâmetro encurta o segmento para evitar afetar a linha do tempo do player de vídeo do cliente.

O exemplo a seguir monta um URL de segmento de anúncio precedente no manifesto. Os segmentos de anúncio usam um índice baseado em zero:

https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/ad_break_id/preroll/ad/0/profile/ENCODING_PROFILE/0.ts?stream_id=SESSION_ID

O exemplo a seguir monta um URL de segmento de anúncio intermediário no manifesto:

https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/ad_break_id/AD_BREAK_ID/ad/0/profile/ENCODING_PROFILE/0.ts?stream_id=SESSION_ID

O exemplo a seguir insere segmentos de anúncio no manifesto:

#EXTM3U
#EXT-X-VERSION:6
#EXT-X-TARGETDURATION:6
#EXT-X-MEDIA-SEQUENCE:0

#EXTINF:5.00,
contentorigin.com/1.ts
#EXTINF:5.00,
contentorigin.com/2.ts
#EXT-X-DISCONTINUITY
#EXTINF:5.00,
https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/ad_break_id/AD_BREAK_ID/ad/0/profile/ENCODING_PROFILE/0.ts?stream_id=SESSION_ID
#EXTINF:5.00,
https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/ad_break_id/AD_BREAK_ID/ad/0/profile/ENCODING_PROFILE/1.ts?stream_id=SESSION_ID
#EXTINF:5.00,
https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/ad_break_id/AD_BREAK_ID/ad/0/profile/ENCODING_PROFILE/2.ts?stream_id=SESSION_ID
#EXT-X-DISCONTINUITY
#EXTINF:5.00,
contentorigin.com/6.mp4
#EXTINF:5.00,
contentorigin.com/7.mp4
#EXTINF:5.00,
contentorigin.com/8.mp4

Criar segmentos de slate

Para preencher a lacuna entre o anúncio e o conteúdo, insira segmentos de slate. Use a matriz slates.segment_durations.values da resposta JSON da API ATM para determinar a duração de cada segmento de slate. Repita a sequência de durações de segmento conforme necessário para preencher todo o intervalo de anúncio.

O exemplo a seguir monta um segmento de slate:

https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/ad_break_id/AD_BREAK_ID/slate/0/profile/ENCODING_PROFILE/0.ts?stream_id=SESSION_ID

O slate/0 no exemplo representa o número de iteração do slate. Consulte a compatibilidade e a capacidade de armazenamento em cache do player de vídeo do cliente para determinar se é necessário começar em 0 e incrementar esse número para cada loop do slate ou mantê-lo em 0 para todas as iterações.

Gerenciar o retorno ao conteúdo

Depois de inserir todos os segmentos do conjunto de anúncios, escolha um dos seguintes métodos para voltar ao stream de conteúdo:

Método	Descrição	Efeitos no player de vídeo do cliente
Preencher com segmentos de slate	Insere os segmentos de slate e repete o slate. Preenche a duração e insere elementos `EXT-X-DISCONTINUITY` entre cada iteração de slate.	Sem efeitos. O player de vídeo volta ao conteúdo sem alterar a linha do tempo.
Realinhar com um único segmento de slate	Insere um único segmento de slate. Usa o parâmetro `d=` para preencher a duração até o início do conteúdo.	Sem efeitos. O player de vídeo volta ao conteúdo sem alterar a linha do tempo.
Retorno imediato	Insere segmentos de conteúdo.	A linha do tempo do player de vídeo é alterada. O player de vídeo do cliente precisa processar a linha do tempo alterada.

Opcional: programar um intervalo de anúncio

Para melhorar a taxa de preenchimento, envie uma notificação de intervalo de anúncio antecipado (EABN) com a duração do conjunto de anúncios, parâmetros de segmentação personalizados e dados de sinal SCTE-35. Para mais detalhes, consulte Enviar notificações de intervalo de anúncio antecipado.