Inserção de anúncios no lado do servidor (SSAI)

A inserção de anúncios no lado do servidor (SSAI) do Amazon IVS permite que você monetize seus streamings com anúncios em vídeo. O IVS SSAI se integra ao AWS Elemental MediaTailor, oferecendo acesso a recursos como decisão de anúncios, segmentação de público e personalização. O IVS fornece uma operação de API para inserir intervalos comerciais em seu streaming ao vivo, permitindo que você dê aos criadores ou operadores o controle sobre quando os anúncios são veiculados. O IVS insere anúncios diretamente no fluxo de vídeo. Isso proporciona uma experiência de visualização fluida e evita a lógica complexa do lado do cliente. Para obter informações sobre os custos associados ao SSAI, consulte Custos do IVS.

Conceitos básicos do SSAI

Este tutorial ajuda você a entender os conceitos básicos da inserção de anúncios no lado do servidor (SSAI) do Amazon IVS. No final deste tutorial, você terá um canal do IVS configurado para a inserção de anúncios no lado do servidor e saberá como inserir intervalos comerciais em seu streaming ao vivo. O IVS SSAI integra-se ao AWS Elemental MediaTailor para gerenciar a decisão de anúncios.

Etapa 1: criar um canal do IVS

Crie um canal do IVS. Você precisará do URL da reprodução do canal para configurar o MediaTailor na próxima etapa. Depois de criar seu canal, salve os seguintes valores:

Etapa 2: criar uma configuração de reprodução do MediaTailor

Crie uma configuração de reprodução do AWS Elemental MediaTailor. Essa configuração conectará seu servidor de decisão de anúncios ao IVS e permitirá a inserção de anúncios em seus streams.

A configuração de reprodução usa o prefixo do URL de reprodução, que é comum em todos os canais do IVS em sua conta e região. Isso significa que você pode usar uma única configuração de reprodução do MediaTailor com vários canais do IVS.

Consulte Criação de uma configuração de reprodução do MediaTailor no Guia do usuário do AWS Elemental MediaTailor para obter instruções. Ao criar a configuração, as seguintes configurações serão necessárias para o IVS SSAI:

Etapa 3: criar uma configuração de anúncio do IVS

Uma configuração de anúncio vincula seus recursos do IVS à sua configuração de reprodução do MediaTailor. Você pode usar uma configuração de reprodução do MediaTailor criada em qualquer região de origem do IVS com uma configuração de anúncio em qualquer outra região de origem do IVS. As regiões de origem do IVS incluem us-west-2, us-east-1, eu-west-1, eu-central-1, ap-northeast-1, ap-northeast-2 e ap-south-1.

Você pode reutilizar uma única configuração de anúncio em vários canais.

Para criar uma configuração de anúncio (AWS CLI):

aws ivs create-ad-configuration --name "my-ad-config" --media-tailor-playback-configurations playbackConfigurationArn="arn:aws:mediatailor:us-west-2:123456789012:playbackConfiguration/my-mediatailor-config"

Salve o valor do ARN da resposta. Você precisa dele na próxima etapa.

Etapa 4: atualizar o canal com a configuração do anúncio

Atualize seu canal do IVS para associá-lo à configuração de anúncio que você criou. Para atualizar o canal (AWS CLI):

aws ivs update-channel --arn "arn:aws:ivs:us-west-2:123456789012:channel/ABcdef12ghIJ" --ad-configuration-arn "arn:aws:ivs:us-west-2:123456789012:ad-configuration/ABcdef12ghIJ"

Etapa 5: iniciar o streaming

Use o endpoint de ingestão e a chave de streaming do seu canal para iniciar o streaming.

Etapa 6: inserir o intervalo comercial

Enquanto seu streaming estiver ao vivo, chame a operação InsertAdBreak para inserir um intervalo comercial. Especifique o ARN do canal e a duração (em segundos) do intervalo comercial.

Para inserir um intervalo comercial (AWS CLI):

aws ivs insert-ad-break --channel-arn "arn:aws:ivs:us-west-2:123456789012:channel/ABcdef12ghIJ" --duration-seconds 30

Após o retorno bem-sucedido de InsertAdBreak, você pode receber um evento EventBridge (alteração de estado de intervalo comercial do IVS) que contém um carimbo de data e hora indicando a hora prevista em que o intervalo do comercial será inserido nas listas de reprodução dos espectadores. Esse é o momento em que o transmissor pode prever que os anúncios começarão a substituir o conteúdo. Se um anúncio não puder ser preenchido (por exemplo, se o seu servidor de decisão de anúncios não retornar um anúncio ou se os anúncios precisarem ser transcodificados pelo MediaTailor), o conteúdo original será exibido em seu lugar.

Integração com o EventBridge

Com o SSAI, um evento de alteração de estado de intervalo comercial do IVS (chamado de intervalo comercial inserido) é adicionado, com os seguintes campos:

Etapa 7: eventos do Player SDK

Em todas as plataformas, o Player SDK exibe eventos quando um intervalo comercial é reproduzido, notificando quando um anúncio começa, progride e termina. Confira um resumo de alto nível dos eventos e cronogramas disponíveis:

Para obter os nomes específicos de eventos e cargas úteis de cada plataforma, consulte a documentação do Player SDK:

Confira abaixo um exemplo de uso de eventos de anúncios no Web SDK para criar um componente de interface de usuário simples de contagem regressiva de anúncios durante um intervalo comercial:

// State 
let podLength = 0;  
let podIndex = 0; 
let remainingSeconds = 0; 
 
// Fired every second during the ad break 
player.addEventListener(PlayerEventType.AD_TIME_UPDATE, (payload) => { 
    podLength = payload.podLength; 
    podIndex = payload.podIndex; 
    remainingSeconds = Math.round(payload.creativeDuration - payload.creativeElapsed); 
    const text = `Ad ${podIndex} of ${podLength} · ${remainingSeconds}s remaining` 
    // Ad 1 of 2 · 20s remaining 
    console.log('Ad countdown text', text); 
    UpdateAdOverlay(text); 
}); 

// Fired when the ad break ends  
player.addEventListener(PlayerEventType.AD_BREAK_ENDED, (payload) => { 
    hideAdOverlay(); 
});

Marcadores de anúncios em conteúdo gravado

Quando um streaming ao vivo é gravado usando gravação automática no Amazon S3, o IVS gera e grava uma lista de reprodução VOD no S3 que inclui marcadores de anúncios SCTE-35 nas posições em que os anúncios foram acionados durante o streaming ao vivo. Para mais detalhes, consulte Referência da lista de reprodução de SSAI.

Experiência do espectador

Por padrão, o MediaTailor preenche e veicula anúncios para todos os espectadores quando você insere um intervalo comercial. Se você estiver usando tokens de autorização de reprodução para seus streamings, poderá impedir que os espectadores recebam anúncios adicionando a declaração "aws:ads-opt-out": true ao seu token JWT de autorização de reprodução.

Quando os espectadores começam a assistir no meio de um intervalo comercial, o IVS arredonda a duração do intervalo comercial para o quartil mais próximo. Por exemplo, um espectador que entrar com 35 segundos restantes em um intervalo comercial de 60 segundos terá um intervalo comercial de 45 segundos.

Ao atualizar sua configuração de reprodução do MediaTailor ou ao adicionar novos anúncios, os espectadores podem não ver os anúncios na primeira vez que você solicita um intervalo comercial, pois o MediaTailor precisa primeiro transcodificar os anúncios. Depois de alguns minutos, as chamadas subsequentes para InsertAdBreak resultarão na visualização de anúncios pelos espectadores. Os logs de transcodificação do MediaTailor registram essas transcodificações.

Parâmetros de rastreamento dos espectadores

Ao configurar um servidor de decisão de anúncios (ADS) no PlaybackConfiguration do Elemental MediaTailor, você pode passar parâmetros para o ADS usando modelos (consulte Como passar parâmetros do MediaTailor para o ADS). Com o IVS SSAI, você pode passar parâmetros para cada espectador usando o token de autorização de reprodução desse usuário, adicionando uma declaração com o seguinte formato:

"aws:ads-player-params": { 
   "key1": "value1", 
   "key2": "value2" 
}

Esses parâmetros são passados para o Elemental MediaTailor para serem preenchidos como as variáveis [player_params.key1] e [player_params.key2] de modelos. As chaves que você incluir nesta lista sempre farão parte do namespace de parâmetros do modelo player_params.

O tamanho total da carga útil de todas as chaves e valores combinados é limitado a 1000 bytes.

Modo de relatórios

Quando um espectador assiste a um anúncio, o cliente ou o servidor pode enviar beacons indicando o progresso da reprodução de cada criativo do anúncio. Por padrão, o MediaTailor lida com o beaconing no lado do servidor. Você pode controlar o modo de relatórios adicionando a seguinte declaração ao token de autorização de reprodução:

"aws:ads-reporting-mode": "CLIENT" | "SERVER"

O valor padrão é SERVER. Quando definido como SERVER, o MediaTailor envia beacons no lado do servidor. Quando definido como CLIENT, o beaconing no lado do servidor é desabilitado e os dados de rastreamento são fornecidos no campo metadata.trackingData do evento adBreakStarted do SDK do Reprodutor do IVS. O SDK do Reprodutor do IVS não chama URLs de beacon.

Problemas conhecidos

Referência da lista de reprodução de SSAI

Lista de reprodução de variante live com SSAI

Quando um anúncio é inserido no stream, o IVS insere as tags documentadas abaixo, antes dos segmentos do anúncio.

1. Declaração de anúncio inserido

#EXT-X-DATERANGE:ID="stitched-ad-1765566299-20000000000",CLASS="live-video-net-stitched-ad",START-DATE="2025-12-12T19:04:59.079Z",DURATION=20.000,X-NET-LIVE-VIDEO-AD-AD-BREAK-ID="test"

2. Alteração da origem do stream

#EXT-X-DATERANGE:ID="source-1765566299",CLASS="live-video-net-stream-source",START-DATE="2025-12-12T19:04:59.079Z",END-ON-NEXT=YES,X-NET-LIVE-VIDEO-STREAM-SOURCE="0f262e65-a709-4ef1-8741-e82d936c"

3. Marcador de descontinuidade

#EXT-X-DISCONTINUITY

Tag HLS padrão que sinaliza que os parâmetros de codificação podem mudar entre o streaming ao vivo e o conteúdo do anúncio.

Segmentos de anúncios

#EXT-X-PROGRAM-DATE-TIME:2025-12-12T19:04:59.079Z 
#EXTINF:2.000,0f262e65-a709-4ef1-8741-e82d936c 
https://4ce388b1cf28.j.cloudfront.hls.live-video.net/v1/segment/CvsCse8Qbs5DU_aRmrVLd72_nK9lo9xS1KjD115LsIXcsD27JfLfkSuamLUivqOTrfHUeGf6Zmx_c9rhq0btTOu7E4F1DaU8knNoebLq6FlKp6q8ysaQdEA10gKCNP92oAQ_0DGLInY462O9HUxgtk5KHj23ZjPhVCxIh3DjWqwaevDci1_q7dYL55rgSKd11SfpsGSS9Yup4g5dfzyGhfz6Y2Skaj34JtoVyd8Nxlppc4jDlZl-6j7YM1i2qdUcM3VNWrZrxCisBXgOPtI3vFdeNcNjPzVdOGjMz5cXcQIp8YOCwnkdkomhn_3xxmB1Zngl3QPao6-oPsjH3qVcMOCuKfKZSmRJGFLvkrO1PefV5ya3eUvihXCMvDE-81EmGp5q9ErEgFpz06rMDbYFWb3z9H8X0t8KzvGDOaqKTYHZ0lgEV-fULeDQ76pDy_OVPwhO2vJMxBpfdQ_IeB1QUK2wJmXJ96Mvv0C2dcb0F7zE3lr_iBGemUjwmb7JmBoM3HdJbpV0TGp8C6vhIAEqCXVzLXdlc3QtMjD3DQ.ts?dna=CmanuVzG9F6kGS2X7ThbGZyZPHWgX2TiBlBMYsvGWLcWaLWyntTaWRp5D9qjZsrGKkzdwoLNY4pri6ZgpxnzqLqWvhcP6zoGu8vifP5NxPgiNKMmYdUmQrqTAf7jbauvE3c6B9ebptAaDEkrbrnG1qF8Cv3kbiABKgl1cy13ZXN0LTIw9w0

Lista de reprodução de variante VOD com SSAI

Quando um streaming ao vivo é gravado, o IVS gera e grava uma lista de reprodução VOD no S3 que inclui marcadores de anúncios SCTE-35 nas posições em que os anúncios foram acionados durante o streaming ao vivo. Para veicular anúncios durante a reprodução de VOD, você veicula essa lista de reprodução do IVS por meio do MediaTailor, que é responsável por inserir segmentos de anúncios na lista de reprodução. O MediaTailor substitui os segmentos originais de VOD durante o intervalo comercial por segmentos de anúncio.

1. Marcador de início de intervalo comercial (SCTE35-OUT)

#EXT-X-DATERANGE:ID="12345678",START-DATE="2025-12-06T00:45:45.723Z",PLANNED-DURATION=20.0,SCTE35-OUT=0xFC302000000000000000FFF00F05F8E7AEFC7FFFFE001B7740000000000000340CFD88

2. Segmentos de anúncios (inseridos pelo MediaTailor)

#EXTINF:2.0, ../../../../segment/b2857627df9428679e888ee8daa979d0b7559801/gk-test-ivs-vod/bd0c7d90-a47c-4a91-b5ec-7d0f9897049b/0/3

3. Marcador de fim do intervalo comercial (SCTE35-IN)

#EXT-X-DATERANGE:ID="12345678",START-DATE="2025-12-06T00:45:45.723Z",END-DATE="2025-12-06T00:46:07.889Z",DURATION=20.0,SCTE35-IN=0xFC302000000000000000FFF00F05F8E7AEFC7F7FFE001B7740000000000000C23E5851