Segmentação

A segmentação está disponível na interface do Google Ads como um menu separado. É possível implementar a segmentação na API Google Ads adicionando o campo adequado a uma consulta. Por exemplo, suponha que você adicione segments.device a uma consulta. Isso resulta em um relatório com uma linha para cada combinação de dispositivo e o recurso especificado na cláusula FROM, além dos valores estatísticos (impressões, cliques, conversões etc.) divididos entre eles.

Na interface do Google Ads, só é possível usar um segmento por vez, mas com a API, você pode especificar vários segmentos na mesma consulta.

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions
FROM campaign

Os resultados do envio dessa consulta para GoogleAdsService.SearchStream são semelhantes a esta string JSON:

{
  "results":[
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"10922"
      },
      "segments":{
        "device":"MOBILE"
      }
    },
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"28297"
      },
      "segments":{
        "device":"DESKTOP"
      }
    }
  ]
}

Neste resultado de amostra, os atributos do primeiro e do segundo objeto, incluindo o nome do recurso, são os mesmos. As impressões são segmentadas por dispositivo, e, portanto, dois ou mais objetos podem ser retornados para a mesma campanha.

Atenção: para cada campo de segmento extra incluído na consulta do relatório, o número de linhas pode aumentar exponencialmente.

Segmentação implícita

Cada relatório é inicialmente segmentado pelo recurso especificado na cláusula FROM. O campo resource_name do recurso na cláusula FROM é retornado, e as métricas são segmentadas por ele, mesmo quando o campo resource_name não está explicitamente incluído na consulta. Por exemplo, quando você especifica ad_group como o recurso na cláusula FROM, ad_group.resource_name é retornado automaticamente, e as métricas são segmentadas implicitamente em relação a ele no nível ad_group.

Para esta consulta:

SELECT metrics.impressions
FROM ad_group

Você recebe uma string JSON como esta:

{
  "results":[
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/2222222222"
      },
      "metrics":{
        "impressions":"237"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/33333333333"
      },
      "metrics":{
        "impressions":"15"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/44444444444"
      },
      "metrics":{
        "impressions":"0"
      }
    }
  ]
}

O campo resource_name de adGroup é sempre retornado porque ad_group é especificado como um recurso na cláusula FROM.

search_term_view

O recurso search_term_view também é segmentado implicitamente por grupo de anúncios, não apenas por um termo de pesquisa, conforme refletido pela estrutura do nome do recurso, que também inclui o grupo de anúncios. Portanto, você pode receber linhas aparentemente duplicadas com os mesmos termos de pesquisa aparecendo nos resultados quando essas linhas pertencem a grupos de anúncios diferentes:

{
  "results":[
    {
      "searchTermView":{
        "resourceName":"customers/1234567890/searchTermViews/111111111~2222222222~Z29vZ2xlIHBob3RvcyBpb3M",
        "searchTerm":"google photos"
      },
      "metrics":{
        "impressions":"3"
      },
      "segments":{
        "date":"2024-06-15"
      }
    },
    {
      "searchTermView":{
        "resourceName":"customers/1234567890/searchTermViews/111111111~33333333333~Z29vZ2xlIHBob3RvcyBpb3M",
        "searchTerm":"google photos"
      },
      "metrics":{
        "impressions":"2"
      },
      "segments":{
        "date":"2024-06-15"
      }
    }
  ]
}

Embora os dois objetos retornados neste exemplo pareçam duplicados, os nomes de recursos deles são diferentes, principalmente na parte do ID do grupo de anúncios. Isso significa que o termo de pesquisa "google photos" é atribuído a dois grupos de anúncios (ID 2222222222 e 33333333333) na mesma data (2024-06-15). Assim, a API funcionou como esperado e não retornou objetos duplicados nesse caso.

Importante: tecnicamente, o recurso search_term_view também é segmentado de forma implícita por uma campanha. No entanto, um grupo de anúncios precisa sempre pertencer a uma campanha. Portanto, usar apenas o grupo de anúncios para eliminar duplicação de linhas de dados é suficiente, porque um grupo de anúncios é a unidade mais granular.

Campos de segmento selecionáveis

Nem todos os campos de segmento podem ser selecionados para um determinado recurso na cláusula FROM. Por exemplo, suponha que você continue a consultar o recurso ad_group. Para que um campo de segmento seja selecionável no recurso ad_group, ele precisa existir na lista Segments de ad_group. A lista Segments é a parte amarela da tabela de campos disponíveis na página de metadados do recurso ad_group.

Observação: a disponibilidade de segmentos em recursos específicos pode variar de acordo com a versão da API. Use o seletor de versão na referência do serviço de campo do Google Ads para verificar a compatibilidade com a versão de destino (v23, v24, v25 ou v26). Por exemplo, na v24 e em versões mais recentes, segments.click_type não pode ser selecionado com ad_group_asset, campaign_asset ou customer_asset, e segments.ad_sub_network_type não pode ser selecionado com campaign_budget (essas combinações só são compatíveis com a v23).

Recursos de segmento

Ao selecionar alguns recursos, talvez seja possível mesclar implicitamente recursos relacionados selecionando os campos deles ao lado dos campos do recurso na cláusula FROM. Esses recursos relacionados podem ser encontrados na lista Attributed Resources no recurso na página de metadados da cláusula FROM. No caso do recurso ad_group, você vai notar que também é possível selecionar campos do recurso campaign. O campo resource_name de qualquer Attributed Resources com pelo menos um campo na cláusula SELECT é retornado automaticamente, mesmo quando o campo resource_name não está explicitamente incluído na consulta.

Assim como os campos Attributed Resource, também é possível selecionar campos Segmenting Resource. Se um determinado recurso tiver uma lista Segmenting Resources na página de metadados, a seleção de campos de um desses recursos listados fará com que a consulta seja segmentada ainda mais pelo resource_name retornado desse Segmenting Resource. Por exemplo, o recurso campaign é listado como um Segmenting Resource para o recurso campaign_budget. Selecionar qualquer campo de campanha, como campaign.name, do recurso campaign_budget não apenas faz com que o campo campaign.name seja retornado, mas também faz com que o campo campaign.resource_name seja retornado e segmentado.

Seleção entre segmentos e métricas

Um determinado campo de segmento pode não ser compatível com alguns dos outros campos de segmento ou com alguns dos campos de métricas. Para identificar quais campos de segmento são compatíveis entre si, consulte a lista selectable_with dos segmentos na cláusula SELECT.

No caso do recurso ad_group, há mais de 50 segmentos disponíveis para seleção. No entanto, a lista selectable_with para segments.hotel_check_in_date é um conjunto muito menor de segmentos compatíveis. Isso significa que, se você adicionar o campo segments.hotel_check_in_date à cláusula SELECT, vai limitar os segmentos disponíveis restantes para selecionar a interseção dessas duas listas.

Restrições de segmento conjunto

Alguns campos de segmento têm restrições de seleção explícitas que exigem que eles sejam solicitados com um segmento pai na cláusula SELECT:

• Se você selecionar segments.ad_sub_network_type (que divide as sub-redes de anúncios do YouTube, como in-stream, in-feed e Shorts), também precisará selecionar segments.ad_network_type.
• Na v25 e em versões mais recentes, ao selecionar segments.ad_sub_format_type (que detalha os anúncios in-stream não puláveis do YouTube por duração), você também precisa selecionar segments.ad_format_type.

Filtragem implícita por seleção de segmento

Quando você seleciona determinados campos de segmento na sua consulta, a API Google Ads pode filtrar implicitamente os resultados para incluir apenas as linhas em que esse segmento é aplicável e tem um valor.

Impacto de segments.keyword.*

Um exemplo comum e importante desse comportamento ocorre ao selecionar qualquer campo em segments.keyword (como segments.keyword.info.text e segments.keyword.ad_group_criterion):

• Exclusão de tráfego sem palavras-chave: se você incluir qualquer campo segments.keyword.* na cláusula SELECT, os resultados serão restritos apenas às linhas diretamente associadas a um critério de grupo de anúncios de palavras-chave da rede de pesquisa.
• Tipos de campanha afetados: os dados de tipos de campanha ou grupos de anúncios que não dependem de palavras-chave da rede de pesquisa são excluídos dos resultados. Isso inclui, sem limitação:
  • Anúncios dinâmicos de pesquisa (DSA): as segmentações de DSA são baseadas no conteúdo do site, não em palavras-chave.
  • Campanhas do Shopping: usam grupos de produtos em vez de palavras-chave.
  • Campanhas Performance Max: embora as campanhas Performance Max possam ser veiculadas na Pesquisa, os relatórios delas geralmente não são segmentados pelos mesmos critérios de palavra-chave.
• Rede de Display: os campos segments.keyword.* pertencem a palavras-chave usadas na rede de pesquisa. Eles não segmentam por palavras-chave da Rede de Display ou outros métodos de segmentação de display.

Dica: se a análise precisar incluir dados de performance de DSA, Shopping ou outras fontes que não sejam palavras-chave de pesquisa, não inclua campos de segments.keyword.* na consulta. Analise os dados de todos os tipos de campanha primeiro e aplique a segmentação de palavras-chave apenas quando o foco for a performance das palavras-chave da rede de pesquisa.

Regras para segmentos na cláusula WHERE

Quando um segmento está na cláusula WHERE, ele também precisa estar na cláusula SELECT. A exceção a essa regra são os seguintes segmentos de data, que são chamados de segmentos principais de data:

• segments.date
• segments.week
• segments.month
• segments.quarter
• segments.year

Regras para campos de segmento principal de data

Os segmentos segments.date, segments.week, segments.month, segments.quarter e segments.year funcionam da seguinte maneira:

Importante: os segmentos de data granulares (segments.date, segments.week e segments.hour) aceitam uma janela de lookback de até 37 meses. As consultas que excedem esse intervalo retornam DateRangeError.REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED na v24 e em versões mais recentes (ou DateRangeError.UNKNOWN na v23). Use segments.month, segments.quarter ou segments.year para dados históricos mais antigos.

• Esses segmentos podem ser filtrados na cláusula WHERE sem aparecer na cláusula SELECT.
• Se algum desses segmentos estiver na cláusula SELECT, um período finito composto por segmentos principais de data precisará ser especificado na cláusula WHERE. Os segmentos de data não precisam ser os mesmos especificados em SELECT.

Exemplos

Inválido: como segments.date está na cláusula SELECT, é necessário especificar um período finito na cláusula WHERE para segments.date, segments.week, segments.month, segments.quarter ou segments.year.	SELECT campaign.name, metrics.clicks, segments.date FROM campaign
Válida: essa consulta retorna nomes de campanhas e cliques acumulados durante o período especificado. Observe que segments.date não precisa aparecer na cláusula SELECT.	SELECT campaign.name, metrics.clicks FROM campaign WHERE segments.date >= '2024-01-01' AND segments.date <= '2024-01-31'
Válida: essa consulta retorna nomes de campanhas e cliques segmentados por data para todos os dias no período inclusivo.	SELECT campaign.name, metrics.clicks, segments.date FROM campaign WHERE segments.date >= '2024-01-01' AND segments.date <= '2024-01-31'
Válida: essa consulta retorna nomes de campanhas e cliques segmentados por mês para todos os dias no período inclusivo.	SELECT campaign.name, metrics.clicks, segments.month FROM campaign WHERE segments.date >= '2024-01-01' AND segments.date <= '2024-01-31'
Válida: essa consulta retorna nomes de campanhas e cliques segmentados por trimestre e, em seguida, por mês para todos os meses no período anual inclusivo.	SELECT campaign.name, metrics.clicks, segments.quarter, segments.month FROM campaign WHERE segments.year >= 2020 AND segments.year <= 2024