As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Rastreamento de anúncios do lado do cliente
Usando a API de rastreamento AWS Elemental MediaTailor do lado do cliente, você pode incorporar controles de player durante intervalos publicitários em fluxos de trabalho de streaming. No rastreamento do lado do cliente, o player ou cliente emite eventos de rastreamento, como impressão e quartil de anúncios, para o Ad Decision Server (ADS) e outras entidades de verificação de anúncios. Esses eventos monitoram o status geral do intervalo publicitário e a disponibilidade individual do anúncio em cada intervalo. Para obter mais informações sobre impressão e quartil (ADS) e outras entidades de verificação de anúncios. Para obter mais informações sobre impressão e quartil e balizamento de anúncios, consulte. [Sinalização do lado do cliente](ad-reporting-client-side-beaconing.md) Para obter mais informações sobre o ADS e outras entidades de verificação de anúncios, consulte. [Integrações de rastreamento de anúncios do lado do cliente](ad-reporting-client-side-ad-tracking-integrations.md)
Para obter informações sobre como passar os parâmetros do jogador e os dados da sessão para o ADS para rastreamento do lado do cliente, consulte e. [MediaTailor variáveis de jogador para solicitações de ADS](variables-player.md) [MediaTailor variáveis de sessão para solicitações de ADS](variables-session.md)
O rastreamento do lado do cliente permite funcionalidades como as seguintes:
+ Temporizadores de contagem regressiva do Ad-break - Para obter mais informações, consulte. [Adicionar cronômetro de contagem regressiva](ad-reporting-client-side-ad-tracking-schema-player-controls.md#ad-reporting-client-side-ad-tracking-schema-player-controls-ad-countdown-timer)
+ Clique no anúncio: para obter mais informações, consulte. [Clique no anúncio](ad-reporting-client-side-ad-tracking-schema-player-controls.md#ad-reporting-client-side-ad-tracking-schema-player-controls-ad-clickthrough)
+ Exibição de anúncios complementares - Para obter mais informações, consulte[Anúncios complementares](ad-reporting-client-side-ad-tracking-schema-player-controls.md#ad-reporting-client-side-ad-tracking-schema-player-controls-companion-ads).
+ Anúncios ignoráveis - Para obter mais informações, consulte. [Anúncios ignoráveis](ad-reporting-client-side-ad-tracking-schema-player-controls.md#ad-reporting-client-side-ad-tracking-schema-player-controls-skippable-ads)
+ Exibição de ícones VAST para conformidade com a privacidade - Para obter mais informações, consulte[Ícones para o Google Por que esse anúncio (WTA)](ad-reporting-client-side-ad-tracking-schema-player-controls.md#ad-reporting-client-side-ad-tracking-schema-player-controls-google-wta).
+ Controle da depuração do jogador durante anúncios - Para obter mais informações, consulte. [Esfregando](ad-reporting-client-side-ad-tracking-schema-player-controls.md#ad-reporting-client-side-ad-tracking-schema-player-controls-scrubbing)
Usando a API de rastreamento MediaTailor do lado do cliente, você pode enviar metadados para o dispositivo de reprodução que habilita a funcionalidade além do rastreamento do lado do cliente:
## Fluxo de trabalho de relatórios do lado do cliente
O diagrama a seguir mostra o fluxo de trabalho completo de relatórios do lado do cliente, desde a inicialização da sessão até a reprodução de anúncios e o beaconing:
O fluxo de trabalho de relatórios do lado do cliente inclui as seguintes etapas:
1. **Inicialização da sessão** - O player de vídeo envia uma solicitação POST ao endpoint da MediaTailor sessão com metadados JSON`adsParams`, incluindo tokens de origem e recursos da sessão. MediaTailor responde com `manifestUrl` e `trackingUrl` para a sessão.
1. **Solicitação de manifesto e decisão de anúncio** - O jogador solicita o manifesto personalizado de MediaTailor. MediaTailor solicita o manifesto do conteúdo original da origem, faz uma solicitação de anúncio ao Ad Decision Server (ADS) usando parâmetros do player, recebe uma resposta VAST com metadados do anúncio e entrega um manifesto personalizado com marcadores de anúncios para o player.
1. **Recuperação de dados de rastreamento** - O jogador pesquisa o URL de rastreamento em intervalos regulares (duração desejada correspondente para HLS ou período mínimo de atualização para DASH). MediaTailor retorna metadados de rastreamento JSON contendo disponibilidades, anúncios, eventos de rastreamento, beacon URLs e dados de verificação de anúncios.
1. **Reprodução e sinalização de anúncios: durante os intervalos publicitários, o player analisa os metadados de rastreamento, dispara beacons** de impressão quando os anúncios começam a ser renderizados, dispara beacons de quartil (início, primeiro quartil, ponto médio, terceiro quartil, completo) no momento apropriado, carrega e executa a verificação de anúncios, se necessário, e envia eventos para serviços de verificação de terceiros. JavaScript viewability/verification
1. **Pesquisa contínua** - O player continua pesquisando o URL de rastreamento durante toda a sessão para receber metadados atualizados para os próximos anúncios e conteúdo dinâmico.
Esse fluxo de trabalho permite recursos avançados, como cronômetros de contagem regressiva de anúncios, funcionalidade de clique, anúncios complementares, anúncios ignoráveis e exibição de ícones VAST para conformidade com a privacidade.
**Topics**
+ [Fluxo de trabalho de relatórios do lado do cliente](#ad-reporting-client-side-workflow)
+ [Habilitando o rastreamento do lado do cliente](#ad-reporting-client-side-enabling)
+ [Parâmetros do servidor de anúncios](#ad-reporting-client-side-ad-server-parameters)
+ [Parâmetros de consulta de interação de origem](#ad-reporting-client-side-origin-interaction-query-parameters)
+ [Recursos configurados por sessão](#ad-reporting-client-side-session-configured-features)
+ [Melhores práticas para rastreamento do lado do cliente](#ad-reporting-client-side-best-practices)
+ [Esquema e propriedades de acompanhamento de anúncios do lado do cliente](ad-reporting-client-side-ad-tracking-schema.md)
+ [Cronometragem da atividade de rastreamento de anúncios](ad-reporting-client-side-ad-tracking-schema-activity-timing.md)
+ [Controles e funcionalidades do player para rastreamento de anúncios do lado do cliente](ad-reporting-client-side-ad-tracking-schema-player-controls.md)
+ [Sinalização do lado do cliente](ad-reporting-client-side-beaconing.md)
+ [Modo híbrido com beacons de anúncios do lado do servidor](ad-reporting-hybrid-mode.md)
+ [Integrações de rastreamento de anúncios do lado do cliente](ad-reporting-client-side-ad-tracking-integrations.md)
+ [Paginando beacons de anúncios com GetTracking](#gettracking)
## Habilitando o rastreamento do lado do cliente
Você ativa o rastreamento do lado do cliente para cada sessão. O player cria um HTTP `POST` para o endpoint do MediaTailor prefixo de inicialização da sessão da configuração. Opcionalmente, o player pode enviar metadados adicionais para usar MediaTailor ao fazer chamadas publicitárias, chamar a origem de um manifesto e invocar ou desativar MediaTailor recursos no nível da sessão.
O exemplo a seguir mostra a estrutura dos metadados JSON:
```
{
"adsParams": { # 'adsParams' is case sensitive
"param1": "value1", # key is not case sensitive
"param2": "value2", # Values can contain spaces. For example, 'value 2' is an allowed value.
},
"origin_access_token":"abc123", # this is an example of a query parameter designated for the origin
"overlayAvails":"on" # 'overlayAvails' is case sensitive. This is an example of a feature that is enabled at the session level.
}
```
Use o MediaTailor console ou a API para configurar o URL do modelo de solicitação do ADS para referenciar esses parâmetros. No exemplo a seguir, `player_params.param1` são os parâmetros do player para`param1`, e `player_params.param2` são os parâmetros do player para`param2`.
```
https://my.ads.com/path?{{param1=[player_params.param1]}}&{{param2=[player_params.param2]}}
```
## Parâmetros do servidor de anúncios
No nível mais alto da estrutura JSON está um objeto `adsParams` JSON. Dentro desse objeto, há key/value pares que MediaTailor podem ser lidos e enviados ao servidor de anúncios em todas as solicitações de sessão. MediaTailor suporta os seguintes servidores de anúncios:
+ Gerenciador de anúncios do Google
+ SpringServe
+ FreeWheel
+ Publica
## Parâmetros de consulta de interação de origem
Quaisquer key/value pares reservados no nível mais alto da estrutura JSON, como, e `adsParams` `availSuppression``overlayAvails`, não são adicionados ao URL da solicitação de origem na forma de parâmetros de consulta. Cada solicitação de manifesto de MediaTailor sessão feita à origem contém esses parâmetros de consulta. A origem ignora parâmetros de consulta estranhos. Por exemplo, MediaTailor pode usar os key/value pares para enviar tokens de acesso à origem.
## Recursos configurados por sessão
Use a estrutura JSON de inicialização de sessão para ativar, desativar ou substituir MediaTailor recursos como, e. `overlayAvails` `availSuppression` `adSignaling` Todas as configurações de recursos passadas durante a inicialização da sessão substituem a configuração no nível da MediaTailor configuração.
**nota**
Os metadados enviados MediaTailor na inicialização da sessão são imutáveis, e metadados adicionais não podem ser adicionados durante a sessão. Use marcadores SCTE-35 para transportar dados que mudam durante a sessão. Para obter mais informações, consulte [MediaTailor variáveis de sessão para solicitações de ADS](variables-session.md).
**Example : Realizando o rastreamento de anúncios do lado do cliente para HLS**
```
POST {{mediatailorURL}}/v1/session/{{hashed-account-id}}/{{origin-id}}/{{asset-id}}.m3u8
{
"adsParams": {
"deviceType": "ipad" # This value does not change during the session.
"uid": "abdgfdyei-2283004-ueu"
}
}
```
**Example : Executando o rastreamento de anúncios do lado do cliente para o DASH**
```
POST {{mediatailorURL}}/v1/session/{{hashed-account-id}}/{{origin-id}}/{{asset-id}}.mpd
{
"adsParams": {
"deviceType": "androidmobile",
"uid": "xjhhddli-9189901-uic"
}
}
```
### Parâmetro do modo de relatório
Você pode especificar o modo de relatório ao inicializar uma sessão incluindo o `reportingMode` parâmetro no corpo da solicitação. Esse parâmetro controla se MediaTailor executa o rastreamento de anúncios do lado do cliente ou do lado do servidor para a sessão.
+ `client`- O player realiza o rastreamento de anúncios e envia beacons para o servidor de anúncios. Esse é o modo padrão se não `reportingMode` for especificado.
+ `server`- MediaTailor realiza o rastreamento de anúncios do lado do servidor e envia beacons diretamente para o servidor de anúncios.
**Example Inicialização da sessão com modo de relatório do lado do servidor**
```
POST {{mediatailorURL}}/v1/session/{{hashed-account-id}}/{{origin-id}}/{{asset-id}}.m3u8
{
"adsParams": {
"deviceType": "ipad",
"uid": "abdgfdyei-2283004-ueu"
},
"reportingMode": "server"
}
```
**Example Inicialização da sessão com modo de relatório do lado do cliente (explícito)**
```
POST {{mediatailorURL}}/v1/session/{{hashed-account-id}}/{{origin-id}}/{{asset-id}}.mpd
{
"adsParams": {
"deviceType": "androidmobile",
"uid": "xjhhddli-9189901-uic"
},
"reportingMode": "client"
}
```
**nota**
O `reportingMode` parâmetro é definido na inicialização da sessão e não pode ser alterado durante a sessão. Se não `reportingMode` for especificado, o MediaTailor padrão é o relatório do lado do cliente para manter a compatibilidade com versões anteriores.
Uma resposta bem-sucedida é um HTTP `200` com um corpo de resposta. O corpo contém um objeto JSON com uma `manifestUrl` e uma `trackingUrl` chave. Os valores são relativos URLs que o player pode usar para fins de reprodução e rastreamento de eventos publicitários.
```
{
"manifestUrl": "/v1/{{dash}}{{master}}/{{hashed-account-id}}/{{origin-id}}/{{asset-id}}.m3u8?aws.sessionId={{session-id}}",
"trackingUrl": "/v1/tracking/{{hashed-account-id}}/{{origin-id}}/{{session-id}}"
}
```
Para obter mais informações sobre o esquema de rastreamento do lado do cliente, consulte. [Esquema e propriedades de acompanhamento de anúncios do lado do cliente](ad-reporting-client-side-ad-tracking-schema.md)
## Melhores práticas para rastreamento do lado do cliente
Esta seção descreve as melhores práticas para rastreamento do lado do cliente em MediaTailor fluxos de trabalho ao vivo e VOD.
### Fluxos de trabalho ao vivo
Pesquise o endpoint de rastreamento em um intervalo que corresponda a cada duração-alvo para o HLS ou o período mínimo de atualização para o DASH, para ter sempre os metadados de rastreamento de anúncios mais atuais. Combinar esse intervalo é especialmente importante em fluxos de trabalho em que os criativos podem ter um componente interativo ou de sobreposição.
**nota**
Alguns jogadores apoiam os ouvintes do evento, o que pode ser usado como uma alternativa à votação. Por exemplo, o recurso de decoração do ID de MediaTailor anúncio precisaria ser ativado para cada sessão. Para obter mais informações, consulte [Decoração de ID do anúncio](ad-id-decoration.md). O uso desse recurso coloca um identificador de intervalo de datas (HLS) ou elemento de evento (DASH) sobre cada anúncio disponível. Os jogadores podem usar essas tags de manifesto como uma solicitação para chamar o endpoint de MediaTailor rastreamento da sessão.
### Fluxos de trabalho de VOD
Após a inicialização bem-sucedida da sessão e depois de MediaTailor receber o primeiro manifesto contendo mídia, você só precisa chamar o endpoint de rastreamento uma vez.
### Inserção de anúncios guiada pelo servidor
As sessões de inserção de anúncios guiada pelo servidor (SGAI) não usam a API. `GetTracking` Em vez disso, quando você usa`aws.reportingMode=CLIENT`, MediaTailor fornece informações de rastreamento na `TRACKING` seção de cada resposta da lista de ativos quando os jogadores solicitam conteúdo publicitário. A resposta de inicialização da sessão não inclui um`trackingUrl`.
A resposta da lista de ativos para sessões SGAI rastreadas pelo lado do cliente tem a seguinte estrutura:
```
{
"ASSETS": [
{ "DURATION": 20.0, "URI": "https://cdn.example.com/ad1/master.m3u8" },
{ "DURATION": 10.0, "URI": "https://cdn.example.com/ad2/master.m3u8" }
],
"TRACKING": {
...VAST tracking events and beacon URLs for each ad...
}
}
```
Ao implementar o rastreamento do lado do cliente para métodos SGAI:
+ Analise a `TRACKING` seção a partir das respostas da lista de ativos em vez de chamar `GetTracking`
+ Use o rastreamento URLs fornecido na lista de ativos para relatórios de eventos publicitários
+ Sinalizadores de rastreamento de disparo com base em eventos reais de reprodução de anúncios no player
+ Gerencie o rastreamento de cada intervalo publicitário de forma independente à medida que as listas de ativos são buscadas
**Importante**
A `TRACKING` seção só é incluída na lista de ativos quando `aws.reportingMode=CLIENT` está definida. Quando os relatórios do lado do servidor são usados (o padrão para SGAI), MediaTailor omite a `TRACKING` seção e, em vez disso, incorpora os dados do beacon no anúncio. URIs Para obter detalhes, consulte [Rastreamento do lado do servidor com inserção de anúncios guiada pelo servidor (SGAI)](ad-reporting-server-side-sgai.md).
## Paginando beacons de anúncios com GetTracking
Use o `GetTracking` endpoint para reduzir o número de anúncios retornados a um player. Por exemplo, se uma janela de manifesto for ampla, abrangendo muito tempo, o número de beacons de anúncios retornados pode afetar o desempenho do jogador.
`GetTracking`retorna um `NextToken` valor que você pode usar para restringir o número de beacons retornados paginando a lista de beacons retornados. Você pode percorrer os `NextToken` valores para encontrar o valor desejado do campo de um anúncio `StartTimeInSeconds` beacon.
+ Na primeira chamada para`GetTracking`, todos os anúncios possíveis que aparecem na janela do manifesto são retornados, incluindo a `NextToken` e o valor de cada um.
+ Se uma `GetTracking` solicitação *não* incluir um`NextToken`, todos os anúncios na janela do manifesto serão retornados.
+ Se uma `GetTracking` solicitação contiver um`NextToken`, mas não houver novos beacons a serem retornados, MediaTailor retornará o mesmo valor `NextToken` que você enviou na solicitação original.
+ Quando não há mais beacons correspondentes a um anúncio, `GetTracking` remove o anúncio de sua resposta.
+ Os tokens `GetTracking` expiram após 24 horas. Se um `NextToken` valor tiver mais de 24 horas, a próxima chamada `GetTracking` retornará um valor nulo`NextToken`.
### Sequência de chamada generalizada GetTracking do jogador
Do player cliente, uma `GetTracking` solicitação é um POST com um corpo de solicitação que contém anúncios `NextToken` e beacons relacionados ao token.
```
https://YouMediaTailorUrl/v1/tracking
{
"NextToken": "value"
.
.
.
}
```
A sequência geral para usar `GetTracking` com `NextToken` é a seguinte:
1. Faça a primeira ligação para`GetTracking`.
Todos os anúncios e beacons e os primeiros `NextToken` para chamadas subsequentes são retornados.
1. Se o valor de `NextToken` for nulo, MediaTailor retornará todos os beacons de anúncios.
1. Se o `NextToken` estiver expirado, MediaTailor retornará uma mensagem de erro do código de retorno HTTP 400.
Faça uma nova chamada `GetTracking` para recuperar `NextToken` s válidos.
1. Examine toda a resposta para encontrar um sinalizador `StartTimeInSeconds` de anúncios que esteja na faixa desejada.
1. Faça uma nova chamada para `GetTracking` com o valor de `NextToken` associado ao desejado`StartTimeInSeconds`.
1. Se necessário, percorra novamente os anúncios retornados até encontrar os anúncios exatos que você deseja reproduzir.
#### Exemplo estendido
Este exemplo mostra como usar `GetTracking`'s `NextToken` para restringir o número de beacons de anúncios retornados a um jogador.
MediaTailor recebe uma `GetTracking` solicitação. A resposta contém um anúncio com ID 9935407 e dois beacons com `StartTimeInSeconds` valores 52.286 e 48.332 segundos.
MediaTailor envia a resposta JSON da `NextToken` seguinte forma:
```
{
"NextToken": JF57ITe48t1441mv7TmLKuZLroxDzfIslp6BiSNL1IJmzPVMDN0lqrBYycgMbKEb
"avails": [
{
"ads": [
{
"adId": "9935407",
"adVerifications": [],
"companionAds": [],
"creativeId": "",
"creativeSequence": "",
"duration": "PT15S",
"durationInSeconds": 15,
"extensions": [],
"mediaFiles": {
"mediaFilesList": [],
"mezzanine": ""
},
"startTime": "PT30S",
"StartTimeInSeconds": 45,
"trackingEvents": [
{
"beaconUrls": [
"http://adserver.com/tracking?event=Impression "
],
"duration": "PT0S",
"durationInSeconds": 0,
"eventId": "9935414",
"eventType": "secondQuartile",
"startTime": "PT52.286S",
"StartTimeInSeconds": 52.286
},
{
"beaconUrls": [
"http://adserver.com/tracking?event=firstQuartile"
],
"duration": "PT0S",
"durationInSeconds": 0,
"eventId": "9935412",
"eventType": "firstQuartile",
"startTime": "PT48.332S",
"StartTimeInSeconds": 48.332
}
],
"vastAdId": ""
}
],
"startTime": "PT46.47S",
"StartTimeInSeconds": 46.47
}
]
}
```
Na próxima `GetTracking` solicitação, MediaTailor responde com o `NextToken` valor: JF57 ITe48t1441mv7 Tm LKu ZLrox DzfIslp SNL1 IJmz PVMDN0lqr BYycg 6Bi Mb. KEb
MediaTailor responde com anúncios e beacons que correspondem aos `StartTimeInSeconds` definidos na chamada `NextToken` anterior.
Suponha que agora a resposta inclua outro anúncio com ID 9235407, além do anúncio anterior com ID 9935407. Os beacons do anúncio ID 9235407 têm s 132.41 e 70.339. `StartTimeInSeconds`
MediaTailor itera sobre todos os beacons na sessão para selecionar aqueles com `StartTimeInSeconds` mais de 52.286 segundos, que são o beacon 3 e o beacon 4 do anúncio com ID 9235407:
```
{
"NextToken": ZkfknvbfsdgfbsDFRdffg12EdffecFRvhjyjfhdfhnjtsg5SDGN
"avails": [
{
"ads": [
{
"adId": "9235407",
"adVerifications": [],
"companionAds": [],
"creativeId": "",
"creativeSequence": "",
"duration": "PT15.816S",
"durationInSeconds": 19.716,
"extensions": [],
"mediaFiles": {
"mediaFilesList": [],
"mezzanine": ""
},
"startTime": "PT2M0S",
"StartTimeInSeconds": 120.0,
"trackingEvents": [
{
"beaconUrls": [
"http://adserver.com/tracking?event=complete"
],
"duration": "PT0S",
"durationInSeconds": 0,
"eventId": "8935414",
"eventType": "firstQuartile",
"startTime": "PT1M10.330S",
"StartTimeInSeconds": 70.339
},
{
"beaconUrls": [
"http://adserver.com/tracking?event=thirdQuartile"
],
"duration": "PT0S",
"durationInSeconds": 0,
"eventId": "8935412",
"eventType": "secondQuartile",
"startTime": "PT2M12.41S",
"StartTimeInSeconds": 132.41
}
],
"vastAdId": ""
},
],
"startTime": "PT36.47S",
"StartTimeInSeconds": 36.47
}
]
}
```