Ao usar a API Video Stitcher, você cria uma sessão de vídeo on demand (VOD) sempre que inserir anúncios dinamicamente veiculados pelo Google Ad Manager antes da entrega aos dispositivos clientes. Quando você cria uma sessão, a resposta inclui o URL de reprodução e informações sobre os anúncios inseridos no vídeo.
Esta página descreve como criar e gerenciar uma sessão VOD ativada pelo Google Ad Manager. Para saber mais sobre as sessões VOD que não usam o Google Ad Manager, consulte Gerenciar uma sessão VOD.
Antes de começar
- Crie uma configuração de VOD. Para a integração com o Google Ad Manager, verifique se o objeto
gamVodConfig
está definido.
Criar uma sessão
É possível criar uma sessão VOD usando o SDK do IMA (que chama a API Video Stitcher) ou diretamente a API Video Stitcher.
Usar o SDK do IMA
Se você estiver fazendo a integração com o SDK do IMA, o SDK do IMA vai criar a sessão VOD.
function requestVodVideoStitcherStream() { const streamRequest = new google.ima.dai.api.VideoStitcherVodStreamRequest(); streamRequest.vodConfigId = 'VOD_CONFIG_ID'; streamRequest.region = 'LOCATION'; streamRequest.projectNumber = 'PROJECT_NUMBER'; streamRequest.oAuthToken = 'OAUTH_TOKEN'; streamRequest.networkCode = 'NETWORK_CODE'; streamManager.requestStream(streamRequest); }
As sessões de VOD ativadas pelo Google Ad Manager precisam usar o rastreamento de anúncios do lado do cliente.
É possível definir ou substituir os seguintes parâmetros opcionais por sessão:
manifestOptions
: especifica quais renderizações de vídeo são geradas no manifesto de vídeo costurado e a ordem das renderizações. Consulte a documentação de opções de manifesto.adTagMacroMap
: uma lista de pares de chave-valor para substituição de macros de tags de anúncios. Consulte a seção Macros de tags de anúncio.
Consulte a próxima seção para saber como definir esses parâmetros usando o SDK do IMA.
Parâmetros e substituições opcionais
function requestVodVideoStitcherStream() { const streamRequest = new google.ima.dai.api.VideoStitcherVodStreamRequest(); streamRequest.vodConfigId = 'VOD_CONFIG_ID'; streamRequest.region = 'LOCATION'; streamRequest.projectNumber = 'PROJECT_NUMBER'; streamRequest.oAuthToken = 'OAUTH_TOKEN'; streamRequest.networkCode = 'NETWORK_CODE'; streamRequest.videoStitcherSessionOptions = { manifestOptions: { "includeRenditions": [ { "bitrateBps": 150000, "codecs": "hvc1.1.4.L126.B0" }, { "bitrateBps": 440000, "codecs": "hvc1.1.4.L126.B0" }, ], "bitrateOrder": "descending", }, "adTagMacroMap": { "my-key": "my-value" } }; streamManager.requestStream(streamRequest); }
Usar a API diretamente
Para criar uma sessão de um vídeo com anúncios unidos, use o
método projects.locations.vodSessions.create
.
REST
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
PROJECT_NUMBER
: o número do seu projeto do Google Cloud localizado no campo Número do projeto na página Configurações do IAMLOCATION
: o local em que a sessão será criada. Use uma das regiões com suporte.Mostrar locaisus-central1
us-east1
us-west1
asia-east1
asia-south1
asia-southeast1
europe-west1
southamerica-east1
VOD_CONFIG_ID
: o identificador definido pelo usuário para a configuração de VOD
Para enviar a solicitação, expanda uma destas opções:
Você receberá uma resposta JSON semelhante a esta:
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/vodSessions/SESSION_ID", "interstitials": { "sessionContent": { "duration": "60s" } }, "playUri": "PLAY_URI", # This is the ad-stitched VOD URI "sourceUri": "VOD_URI", "adTagUri": "AD_TAG_URI", "assetId": "ASSET_ID", "adTracking": "SERVER", "vodConfig": "projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID" }
C#
Antes de testar esta amostra, siga as instruções de configuração do C# no Guia de início rápido da API Video Stitcher: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API C# da API Video Stitcher.
Para autenticar na API Video Stitcher, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Go
Antes de testar esta amostra, siga as instruções de configuração do Go no Guia de início rápido da API Video Stitcher: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Go da API Video Stitcher.
Para autenticar na API Video Stitcher, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Java
Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido da API Video Stitcher: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Java da API Video Stitcher.
Para autenticar na API Video Stitcher, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Antes de testar esta amostra, siga as instruções de configuração do Node.js no Guia de início rápido da API Video Stitcher: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Node.js da API Video Stitcher.
Para autenticar na API Video Stitcher, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
PHP
Antes de testar esta amostra, siga as instruções de configuração do PHP no Guia de início rápido da API Video Stitcher: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API PHP da API Video Stitcher.
Para autenticar na API Video Stitcher, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido da API Video Stitcher: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Python da API Video Stitcher.
Para autenticar na API Video Stitcher, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Ruby
Antes de testar esta amostra, siga as instruções de configuração do Ruby no Guia de início rápido da API Video Stitcher: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Ruby da API Video Stitcher.
Para autenticar na API Video Stitcher, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
A API Video Stitcher gera um ID de sessão exclusivo para cada solicitação. Uma sessão expira após 4 horas.
A resposta vai ser semelhante a esta:
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/vodSessions/SESSION_ID", "interstitials": { "adBreaks": [ { "progressEvents": [ { "timeOffset": "0s", "events": [ { "type": "IMPRESSION", "uri": "https://securepubads.g.doubleclick.net/pcs/view..." }, { "type": "START", "uri": "https://pubads.g.doubleclick.net/pagead/interaction/..." }, ... ] }, ... ], "ads": [ { "duration": "10s", "activityEvents": [ { "type": "ERROR", "uri": "https://pubads.g.doubleclick.net/pagead/interaction/..." }, { "type": "CLICK_THROUGH", "uri": "https://pubads.g.doubleclick.net/pcs/click...", "id": "GDFP" }, ... ] } ], "endTimeOffset": "10s", "startTimeOffset": "0s" } ], "sessionContent": { "duration": "70s" } }, "playUri": "PLAY_URI", "sourceUri": "VOD_URI", "adTagUri": "AD_TAG_URI", "assetId": "ASSET_ID", "adTracking": "SERVER", "vodConfig": "projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID" }
A resposta é um
objeto VodSession
que contém os seguintes campos:
- Um campo
name
que mostra o VOD SESSION_ID. Use esse ID para receber a sessão. - Um campo
interstitials
que contém metadados sobre os anúncios que foram inseridos (consulte os conceitos de metadados de anúncios). - Um campo
playUri
que mostra o URL que o dispositivo cliente usa para reproduzir o recurso de vídeo condicionado.
Se você estiver gerando uma sessão em nome dos dispositivos dos seus clientes, defina os seguintes parâmetros usando cabeçalhos HTTP:
Parâmetro | Cabeçalho HTTP |
---|---|
CLIENT_IP | x-user-ip |
REFERRER_URL | referer |
USER_AGENT | user-agent |
É possível adicionar os seguintes cabeçalhos à solicitação curl
anterior:
-H "x-user-ip: CLIENT_IP" \ -H "referer: REFERRER_URL" \ -H "user-agent: USER_AGENT" \
Macros de tags de anúncio
Uma tag de anúncio pode conter macros, o que pode resultar em uma tag de anúncio diferente para cada sessão. As macros são indicadas por colchetes na tag do anúncio, conforme ilustrado neste exemplo:
AD_TAG_URI¯o=[my-key]
O adTagUri
é definido na configuração de VOD.
Para substituir o valor na macro de tag de anúncio, forneça um mapeamento no campo adTagMacroMap
. Por exemplo, se você quiser substituir
a macro [my-key]
pela string my-value
, forneça o
seguinte:
{ ... "adTagMacroMap": { "my-key": "my-value" }, ... }
Quando a API Video Stitcher solicita os metadados do anúncio, ela usa a seguinte tag de anúncio:
AD_TAG_URI¯o=my-value
Acessar uma sessão
Para acessar a sessão de um vídeo com anúncios, use o
método projects.locations.vodSessions.get
.
REST
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
PROJECT_NUMBER
: o número do seu projeto do Google Cloud localizado no campo Número do projeto na página Configurações do IAMLOCATION
: o local da sua sessão. Use uma das regiões compatíveis.Mostrar locaisus-central1
us-east1
us-west1
asia-east1
asia-south1
asia-southeast1
europe-west1
southamerica-east1
SESSION_ID
: o identificador da sessão VOD
Para enviar a solicitação, expanda uma destas opções:
Você receberá uma resposta JSON semelhante a esta:
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/vodSessions/SESSION_ID", "interstitials": { "adBreaks": [ { "progressEvents": [ { "timeOffset": "0s", "events": [ { "type": "IMPRESSION", "uri": "https://securepubads.g.doubleclick.net/pcs/view..." }, { "type": "START", "uri": "https://pubads.g.doubleclick.net/pagead/interaction/..." }, ... ] }, ... ], "ads": [ { "duration": "10s", "activityEvents": [ { "type": "ERROR", "uri": "https://pubads.g.doubleclick.net/pagead/interaction/..." }, { "type": "CLICK_THROUGH", "uri": "https://pubads.g.doubleclick.net/pcs/click...", "id": "GDFP" }, ... ] } ], "endTimeOffset": "10s", "startTimeOffset": "0s" } ], "sessionContent": { "duration": "70s" } }, "playUri": "PLAY_URI", "sourceUri": "VOD_URI", "adTagUri": "AD_TAG_URI", "assetId": "ASSET_ID", "adTracking": "SERVER", "vodConfig": "projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID" }
C#
Antes de testar esta amostra, siga as instruções de configuração do C# no Guia de início rápido da API Video Stitcher: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API C# da API Video Stitcher.
Para autenticar na API Video Stitcher, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Go
Antes de testar esta amostra, siga as instruções de configuração do Go no Guia de início rápido da API Video Stitcher: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Go da API Video Stitcher.
Para autenticar na API Video Stitcher, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Java
Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido da API Video Stitcher: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Java da API Video Stitcher.
Para autenticar na API Video Stitcher, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Antes de testar esta amostra, siga as instruções de configuração do Node.js no Guia de início rápido da API Video Stitcher: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Node.js da API Video Stitcher.
Para autenticar na API Video Stitcher, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
PHP
Antes de testar esta amostra, siga as instruções de configuração do PHP no Guia de início rápido da API Video Stitcher: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API PHP da API Video Stitcher.
Para autenticar na API Video Stitcher, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido da API Video Stitcher: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Python da API Video Stitcher.
Para autenticar na API Video Stitcher, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Ruby
Antes de testar esta amostra, siga as instruções de configuração do Ruby no Guia de início rápido da API Video Stitcher: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Ruby da API Video Stitcher.
Para autenticar na API Video Stitcher, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Exemplo de playlist com anúncios integrados
Confira a seguir um exemplo de playlist de VOD de origem antes da junção de anúncios:
#EXTM3U
#EXT-X-TARGETDURATION:6
#EXT-X-VERSION:4
#EXT-X-PLAYLIST-TYPE:VOD
#EXT-X-MEDIA-SEQUENCE:0
#EXTINF:6.000,
segment_01.ts
#EXTINF:6.000,
segment_02.ts
#EXTINF:6.000,
segment_03.ts
#EXTINF:6.000,
segment_04.ts
#EXTINF:6.000,
segment_05.ts
#EXTINF:6.000,
segment_06.ts
#EXT-X-ENDLIST
O exemplo a seguir mostra uma playlist de VOD de origem após a junção de anúncios com anúncios precedentes, intermediários e finais:
#EXTM3U
#EXT-X-VERSION:4
#EXT-X-TARGETDURATION:6
#EXT-X-PLAYLIST-TYPE:VOD
#EXT-X-DISCONTINUITY
#EXTINF:4.000,
https://redirector.googlevideo.com/videoplayback/...
#EXTINF:4.000,
https://redirector.googlevideo.com/videoplayback/...
#EXTINF:1.990,
https://redirector.googlevideo.com/videoplayback/...
#EXT-X-DISCONTINUITY
#EXTINF:6.000,
segment_01.ts
#EXTINF:6.000,
segment_02.ts
#EXT-X-DISCONTINUITY
#EXTINF:4.000,
https://redirector.googlevideo.com/videoplayback/...
#EXTINF:0.990,
https://redirector.googlevideo.com/videoplayback/...
#EXT-X-DISCONTINUITY
#EXTINF:6.000,
segment_03.ts
#EXTINF:6.000,
segment_04.ts
#EXTINF:6.000,
segment_05.ts
#EXTINF:6.000,
segment_06.ts
#EXT-X-DISCONTINUITY
#EXTINF:4.000,
https://redirector.googlevideo.com/videoplayback/...
#EXTINF:4.000,
https://redirector.googlevideo.com/videoplayback/...
#EXTINF:1.990,
https://redirector.googlevideo.com/videoplayback/...
#EXT-X-ENDLIST
Processar o acompanhamento de anúncios do lado do cliente
O SDK do IMA vai processar automaticamente o acompanhamento de anúncios do lado do cliente.
Inspecionar sessões de VOD ativadas pelo Google Ad Manager
Para inspecionar as sessões de VOD e os detalhes da tag de anúncio, use o Monitoramento da atividade de streaming no Ad Manager.