Campanhas de vídeo

Com as campanhas de vídeo, você pode mostrar anúncios em vídeo no YouTube e em sites e apps de parceiros de vídeo do Google.

Limitações da API

A API Google Ads é usada principalmente para buscar e gerar relatórios sobre campanhas, grupos de anúncios, anúncios e critérios de vídeo. Não é possível criar ou modificar campanhas de vídeo usando a API Google Ads, com as seguintes exceções e comportamentos específicos da versão:

• Mutabilidade de VideoResponsiveAdInfo: a partir da v24, os objetos VideoResponsiveAdInfo são mutáveis (em versões anteriores, eles são imutáveis). Ao criar ou modificar VideoResponsiveAdInfo, os campos videos, business_name e logo_images são obrigatórios.
• Adequação de brand safety: a partir da v24, o campaign.video_brand_safety_suitability no nível da campanha foi removido. Consulte a adequação de brand safety no nível da conta usando customer.video_brand_safety_suitability.
• Experimentos de campanha de vídeo: a partir da v24, experiment.video_experiment está disponível para configurar experimentos de YOUTUBE_CUSTOM que consistem em campanhas de vídeo.

Alternativas para o gerenciamento de campanhas

Se você precisar criar ou gerenciar campanhas de vídeo de forma programática, considere as seguintes opções:

• Scripts do Google Ads: você pode gerenciar campanhas de vídeo usando os scripts do Google Ads. Isso permite o gerenciamento automatizado na interface do Google Ads.
• Campanhas Geração de Demanda: se o objetivo é veicular anúncios em vídeo nos Serviços do Google, incluindo o YouTube, as campanhas Geração de Demanda são totalmente compatíveis com a API Google Ads para criação e gerenciamento.

Receber dados de performance

É possível recuperar dados de performance das suas campanhas de vídeo, grupos de anúncios e critérios usando GoogleAdsService.SearchStream ao filtrar por campaign.advertising_channel_type = 'VIDEO'.

Observação: use metrics.video_trueview_views, metrics.video_trueview_view_rate e metrics.trueview_average_cpv para as métricas de visualização TrueView. A partir da v25, também é possível selecionar segments.ad_sub_format_type (ao lado de segments.ad_format_type) para detalhar os anúncios in-stream não puláveis por duração, bem como as métricas de engajamento social em vídeos (metrics.youtube_comments, metrics.youtube_likes e metrics.youtube_shares).

Desempenho do grupo de anúncios

A consulta a seguir recupera as métricas de campanhas de vídeo e grupos de anúncios, incluindo as visualizações de vídeo TrueView e as taxas de conclusão de quartil, do recurso ad_group:

SELECT
  campaign.id,
  campaign.name,
  campaign.advertising_channel_type,
  ad_group.id,
  ad_group.name,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.video_trueview_views,
  metrics.video_quartile_p100_rate
FROM ad_group
WHERE campaign.advertising_channel_type = 'VIDEO'

Relatórios de critérios e posições de vídeo

Como ad_group_criterion não é compatível com métricas ou segmentos diretamente, use recursos de visualização de critérios, como managed_placement_view, para recuperar métricas de performance de vídeos do YouTube, canais do YouTube ou outras seleções manuais de canais segmentadas:

SELECT
  campaign.id,
  ad_group.id,
  ad_group_criterion.criterion_id,
  ad_group_criterion.type,
  ad_group_criterion.youtube_video.video_id,
  ad_group_criterion.youtube_channel.channel_id,
  metrics.impressions,
  metrics.video_trueview_views
FROM managed_placement_view
WHERE campaign.advertising_channel_type = 'VIDEO'
  AND ad_group_criterion.type IN ('YOUTUBE_VIDEO', 'YOUTUBE_CHANNEL')
  AND segments.date DURING LAST_30_DAYS

Relatórios de alcance e frequência

Para campanhas de vídeo, é possível consultar as métricas de alcance Unique Reach nos recursos campaign e customer (a partir da v26) para medir o número de pessoas que visualizaram seus anúncios em frequências de impressão específicas.

As seguintes métricas de usuário único medem o alcance do público-alvo em intervalos de frequência:

• metrics.unique_users: o número de pessoas únicas que viram seu anúncio pelo menos uma vez no período selecionado (até 92 dias). Não é possível agregar os dados entre as linhas.
• metrics.unique_users_two_plus a metrics.unique_users_ten_plus: o número de pessoas únicas que viram seu anúncio pelo menos 2 a 10 vezes, respectivamente, em períodos de até 31 dias (com metrics.unique_users_six_plus a metrics.unique_users_nine_plus completando o conjunto de 2+ a 10+ na v26 e em versões mais recentes).
• metrics.average_impression_frequency_per_user: o número médio de vezes que um usuário único viu seu anúncio durante o período solicitado (até 92 dias). Essa métrica está disponível apenas no recurso campaign, não pode ser agregada em linhas e não tem um campo _info complementar.

Na v26 e em versões mais recentes, cada métrica de alcance de usuário único tem um campo de metadados complementar do tipo ReachMetricInfo: metrics.unique_users_info e metrics.unique_users_two_plus_info até metrics.unique_users_ten_plus_info.

Na linguagem de consulta do Google Ads (GAQL), os campos complementares metrics.unique_users*_info são métricas MESSAGE com filterable: false e sortable: false. Por isso, não é possível usá-los em cláusulas WHERE ou ORDER BY. Selecione esses campos diretamente na cláusula SELECT (por exemplo, metrics.unique_users_info). Não anexe .reach_metric_states na cláusula SELECT, porque a seleção de campos de mensagem aninhados na GAQL falha com UNRECOGNIZED_FIELD. Em vez disso, selecionar metrics.unique_users_info retorna uma mensagem ReachMetricInfo que contém o campo de tipo enumerado repetido reach_metric_states do tipo ReachMetricState, que descreve se a métrica foi suprimida ou está completa.

Sempre que uma métrica de alcance é suprimida ou está fora da janela de retenção (PRIVACY_SUPPRESSION, QUALITY_SUPPRESSION ou DATE_RANGE_BEYOND_RETENTION), o campo optional int64 em Metrics é desativado (o que resulta em 0 se a presença do campo não for verificada), enquanto LOW_QUALITY ainda preenche a métrica numérica.

Os valores do tipo enumerado ReachMetricState indicam o status dos dados de alcance:

• COMPLETE: a métrica de alcance está completa, sem supressão devido a limites de privacidade, qualidade ou outros.
• PRIVACY_SUPPRESSION: os dados de alcance foram suprimidos para proteger a privacidade do usuário (por exemplo, quando o volume do público-alvo não atende aos limites de k-anonimato).
• QUALITY_SUPPRESSION: os dados de alcance foram suprimidos devido aos requisitos de qualidade de dados.
• LOW_QUALITY: a métrica de alcance foi calculada, mas está sinalizada como de baixa qualidade.
• DATE_RANGE_BEYOND_RETENTION: as métricas de alcance não estão disponíveis porque o período selecionado excede o período de retenção de dados de 3 anos para dados de alcance.

A consulta a seguir recupera as métricas de alcance sem duplicação de 30 dias e os estados de supressão para campanhas de vídeo, segmentadas por dispositivo e formato do anúncio. Omita o segmento segments.date da cláusula SELECT para que as métricas de alcance e frequência de N+ sejam deduplicadas em todo o período, em vez de por dia:

SELECT
  campaign.id,
  campaign.name,
  segments.device,
  segments.ad_format_type,
  segments.ad_sub_format_type,
  metrics.unique_users,
  metrics.unique_users_info,
  metrics.unique_users_two_plus,
  metrics.unique_users_two_plus_info,
  metrics.unique_users_six_plus,
  metrics.unique_users_six_plus_info,
  metrics.unique_users_ten_plus,
  metrics.unique_users_ten_plus_info
FROM campaign
WHERE campaign.advertising_channel_type = 'VIDEO'
  AND segments.date DURING LAST_30_DAYS

Recursos, períodos e segmentos compatíveis

As consultas de alcance e frequência exigem um filtro segments.date finito dentro da janela de data máxima da métrica. As consultas sem um filtro de data ou que excedem a janela retornam campos de alcance não definidos:

Métrica	Recursos	Período máximo	Segmentos compatíveis
metrics.unique_users	campaign, customer (v26 e mais recentes)	92 dias	segments.date, segments.device, segmentos de formato do anúncio (v26 e mais recentes), segmentos de rede de publicidade (v26 e mais recentes) e segmentos demográficos ajustados
metrics.average_impression_frequency_per_user	campaign	92 dias	segments.date, segments.device e segmentos demográficos ajustados
metrics.unique_users_two_plus a metrics.unique_users_ten_plus	campaign, customer (v26 e mais recentes)	31 dias	segments.date, segments.device, segmentos de formato do anúncio (v26 e mais recentes) e segmentos de rede de publicidade (v26 e mais recentes)
metrics.unique_users*_info (v26 e mais recentes)	campaign, customer	Métrica de base de correspondências	segments.date, segments.device, segmentos de formato do anúncio e segmentos de rede de publicidade

Ao segmentar consultas de alcance, aplique as seguintes restrições de segmento conjunto:

• Segmentos de formato do anúncio x rede de publicidade: é possível segmentar por formato do anúncio (segments.ad_format_type, opcionalmente com segments.ad_sub_format_type) ou por rede de publicidade (segments.ad_network_type, opcionalmente com segments.ad_sub_network_type), mas não é possível combinar segmentos de formato do anúncio e de rede de publicidade na mesma consulta. Sempre selecione o segmento pai (segments.ad_format_type ou segments.ad_network_type) ao selecionar o subsegmento dele. O segmento segments.ad_sub_format_type detalha os anúncios in-stream não puláveis por duração e retorna UNSEGMENTED para outros formatos de anúncio, enquanto o segmento segments.ad_sub_network_type detalha as plataformas do YouTube (YOUTUBE_INSTREAM, YOUTUBE_INFEED e YOUTUBE_SHORTS) apenas para campanhas Geração de Demanda e retorna UNSEGMENTED para campanhas de vídeo.
• Segmentos demográficos ajustados: os segmentos segments.adjusted_age_range e segments.adjusted_gender estão disponíveis apenas para contas na lista de permissões, precisam ser selecionados juntos e não podem ser combinados com métricas de metrics.unique_users_*_plus, campos de metrics.unique_users*_info ou segmentos de rede de publicidade.

Observação: as métricas de alcance e frequência não podem ser agregadas em várias linhas. No recurso customer, os campos campaign não são filtráveis, e as métricas de alcance de usuários únicos eliminam a duplicação de alcance em todos os tipos de campanha compatíveis na conta. Consulte Supressão de métricas de alcance e valores zero para mais detalhes.