Esta página foi traduzida pela API Cloud Translation.

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

Este guia descreve como inserir intervalos de anúncios usando o método de metadados de tempo de bloco de anúncios (ATM) para buscar o tempo e a duração exatos dos intervalos, incluindo anúncios pre-roll.

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

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

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

Pré-requisitos

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

Interface do Ad Manager:configure uma transmissão ao vivo para DAI.
API Ad Manager:use uma biblioteca de cliente (opções disponíveis) para chamar o método LiveStreamEventService.createLiveStreamEvents. 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 de stream, o app extrai o ID da sessão e os metadados da DAI do Google para incluir na solicitação de manifesto de 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 preparar a junção de anúncios.

Recuperar metadados de tempo de um bloco de anúncios

Para recuperar a duração do bloco de anúncios, siga estas etapas:

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

Gerar um token HMAC assinado

Para autenticar suas solicitações, siga estas etapas:

Crie uma string de token concatenando os seguintes parâmetros em ordem alfabética, separados por um til ~:

Parâmetro	Obrigatório ou opcional	Descrição
`ad_break_id`	Obrigatório	Uma string especificada para identificar o intervalo de publicidade, por exemplo, `ad-break-1`. Para anúncios precedentes, use `preroll`.
`custom_asset_key`	Obrigatório	A chave de recurso personalizada do evento de transmissão ao vivo.
`cust_params`	Opcional	Parâmetros de segmentação personalizada. Para mais detalhes, consulte Fornecer parâmetros de segmentação ao stream.
`exp`	Obrigatório	O tempo em que este token expira, medido como o número total de segundos que se passaram desde a época do Unix.
`network_code`	Obrigatório	Seu código de rede do Google Ad Manager. Para mais detalhes, consulte Encontrar informações da conta do Ad Manager.
`pd`	Obrigatório	A duração do intervalo de anúncio em milissegundos. Para anúncios precedentes, a DAI do Google substitui esse parâmetro pelas configurações do evento de transmissão ao vivo.
`scte35`	Opcional	Sinal SCTE-35 codificado em Base64. Verifique se o indicador está correto. Se estiver incorreto, uma mensagem será enviada ao cabeçalho HTTP `X-Ad-Manager-Dai-Warning` na resposta, e o indicador ainda será propagado para criar um intervalo comercial. Para mais detalhes sobre os marcadores de intervalo de anúncio compatíveis, consulte Integração do HLS.

Baixe sua chave de autenticação da DAI do Google do tipo HMAC. Para mais detalhes, consulte Autenticar solicitações de stream de vídeo da DAI.
Use a chave HMAC baixada para gerar a assinatura SHA256 da string do token.
Concatene a string de token e a assinatura gerada.
Aplique a codificação de URL à string concatenada. A string codificada é o token HMAC assinado para autenticar as solicitações da API de metadados de tempo do pod de anúncio (ATM, na sigla em inglês).

O exemplo a seguir gera um token HMAC assinado para anúncios pre-roll:

custom_asset_key="CUSTOM_ASSET_KEY"
exp="1750700000" # Expired on Mon Jun 23 2025 13:33:20 GMT-0400 (Eastern Daylight Time)
network_code="NETWORK_CODE"
ad_break_id="preroll"
pd="0" # Pod duration value is overridden by the livestream event settings.

# The HMAC authentication key associated with your livestream event in Google Ad Manager.
secret_key="24E96382584C328087546B0E8454F26158564E8466FD2BE3D8A996B38445876C"

# Concatenate the parameters, keep the parameters alphabetically ordered by name.
token_string="ad_break_id=${ad_break_id}~custom_asset_key=${custom_asset_key}~exp=${exp}~network_code=${network_code}~pd=${pd}"

# Calculate the SHA256 signature of the token_string.
hmac_signature=$(echo -n "$token_string" | openssl dgst -sha256 -hmac "$secret_key" | awk '{print $2}')

# Concatenate the token string and the signature.
signed_token="${token_string}~hmac=${hmac_signature}"

url_encode() {
    local string="${1}"
    local strlen=${#string}
    local encoded=""
    local pos c
    for (( pos=0 ; pos<strlen ; pos++ )); do
        c=${string:$pos:1}
        case "$c" in
            [-_.~a-zA-Z0-9] ) o="${c}" ;;
            *   ) printf -v o '%%%02x' "'$c"
        esac
        encoded+="${o}"
    done
    echo "${encoded}"
}

# Apply URL encoding to the concatenated string.
url_encoded_signed_token=$(url_encode "$signed_token")

echo "Signed HMAC token:"
echo "${url_encoded_signed_token}"

# Example output:
# ad_break_id%3Dpreroll~custom_asset_key%3DiYdOkYZdQ1KFULXSN0Gi7g~exp%3D1489680000~network_code%3D21775744923~pd%3D180000~pod_id%3D5~hmac%3D24E96382584C328087546B0E8454F26158564E8466FD2BE3D8A996B38445876C

Solicitar metadados de tempo de solicitação para anúncios precedentes

Verifique as configurações de pré-roll do seu evento de transmissão ao vivo usando as seguintes opções:

Para recuperar os resultados da decisão de anúncio pre-roll, 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 metadados de um conjunto de anúncios intermediários, siga estas etapas:

Analise o manifesto da 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 bloco de anúncios e da tela. A API retorna um objeto JSON com os resultados da decisão do conjunto 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ê vai 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
          ]
        }
      }
    }
  }
}

Inserir anúncios no manifesto de conteúdo

As seções a seguir explicam como modificar o manifesto da 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 seu 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 manifesto de exemplo 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úncios 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. No final do intervalo, adicione a criptografia novamente inserindo um EXT-X-KEY adequado.

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

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 o ads.segment_durations.values fornecido na resposta JSON da API ATM.

Para encerrar um bloco de anúncios antes do tempo ao detectar uma tag EXT-X-CUE-IN, adicione o parâmetro d= ao URL do segmento final do anúncio. 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 pre-roll no manifesto. Observação: os segmentos de anúncios usam um índice com base 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 inserção

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

O exemplo a seguir monta um segmento de programação:

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 da iteração da tela. Consulte a compatibilidade e a capacidade de armazenamento em cache do player de vídeo do cliente para determinar se você deve começar em 0 e aumentar esse número a cada loop da tela ou manter 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 ardósia	Insere os segmentos de claquete e faz um loop dela. Preenche a duração e insere elementos `EXT-X-DISCONTINUITY` entre cada iteração de bloco.	Sem efeitos. O player de vídeo volta ao conteúdo sem alterar a linha do tempo.
Realinhar com um único segmento de lista	Insere um único segmento de quadro. 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	Inserir 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 aumentar sua 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 personalizada e dados de sinal SCTE-35. Para mais detalhes, consulte Enviar notificações antecipadas de intervalo publicitário.