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 do 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 de v24, a campaign.video_brand_safety_suitability no nível da campanha será removida. Consulte a adequação de brand safety no nível da conta usando customer.video_brand_safety_suitability.
• Experimentos de campanhas de vídeo: a partir de 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 de v25, também será 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, além das métricas de engajamento social em vídeo (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 campanha de vídeo e de grupo 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 da campanha

Para campanhas de vídeo, é possível consultar as métricas de alcance Unique Reach no recurso campaign para medir o número de pessoas que viram 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 esses dados em várias 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). Ele não pode ser agregado em linhas e não tem um campo _info complementar.

Na v26 e em versões mais recentes, cada métrica de alcance 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 de alcance complementar são métricas MESSAGE selecionadas 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 de 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 e os estados de supressão de uma campanha de vídeo:

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  segments.device,
  metrics.unique_users,
  metrics.unique_users_info,
  metrics.average_impression_frequency_per_user,
  metrics.unique_users_two_plus,
  metrics.unique_users_two_plus_info,
  metrics.unique_users_three_plus,
  metrics.unique_users_three_plus_info,
  metrics.unique_users_four_plus,
  metrics.unique_users_four_plus_info,
  metrics.unique_users_five_plus,
  metrics.unique_users_five_plus_info,
  metrics.unique_users_six_plus,
  metrics.unique_users_six_plus_info,
  metrics.unique_users_seven_plus,
  metrics.unique_users_seven_plus_info,
  metrics.unique_users_eight_plus,
  metrics.unique_users_eight_plus_info,
  metrics.unique_users_nine_plus,
  metrics.unique_users_nine_plus_info,
  metrics.unique_users_ten_plus,
  metrics.unique_users_ten_plus_info
FROM campaign
WHERE campaign.advertising_channel_type = 'VIDEO'
  AND segments.date BETWEEN '2026-01-01' AND '2026-01-31'

Observação : não é possível agregar métricas de alcance e frequência em várias linhas. Enquanto metrics.unique_users e metrics.average_impression_frequency_per_user aceitam períodos de até 92 dias e podem ser segmentados por segments.date, segments.device, segments.adjusted_age_range e segments.adjusted_gender, as métricas de intervalo de frequência de unique_users_*_plus (até 31 dias) e todos os campos complementares de metrics.unique_users*_info só aceitam segments.date e segments.device. Além disso, os campos complementares metrics.unique_users*_info são métricas MESSAGE com filterable: false e sortable: false, portanto, não podem ser usados em cláusulas WHERE ou ORDER BY. Consulte Supressão de métricas de alcance e valores zero para mais detalhes sobre como lidar com métricas de alcance suprimidas em relatórios.