API de relatórios principais — segmentos

Este documento descreve a sintaxe e fornece considerações para o uso de segmentos na API de relatórios principais.

Introdução

Quando você usa o recurso de segmentação da API de relatórios principais, pode solicitar um segmento nessa API de duas formas:

  1. Segmentos por ID: consulte usando o ID numérico de um segmento integrado ou personalizado.
  2. Segmentos dinâmicos: especifique o segmento de forma dinâmica no momento da solicitação.

Segmentos por ID

Você pode solicitar um segmento na API de relatórios principais usando o ID de um segmento integrado ou personalizado. É possível recuperar todos os segmentos disponíveis para um usuário com o método list do conjunto de segmentos na API de gerenciamento do Google Analytics. Para cada segmento, o ID está disponível na propriedade id do recurso de segmentos.

Para saber mais sobre como usar os IDs de segmento nas solicitações da API, consulte a Referência da API de relatórios principais.

Segmentos dinâmicos

Também é possível criar e usar um segmento de forma dinâmica realizando uma solicitação de API. Normalmente, ao criar um segmento dinâmico, você deve considerar os seguintes aspectos:

  1. Seleção de usuários x sessões
  2. Uso de condições x sequências
  3. Uso de escopos de métricas

As considerações necessárias para criar um segmento dinâmico estão descritas detalhadamente abaixo. Para analisar a sintaxe completa para segmentos dinâmicos, consulte a Referência de sintaxe dos segmentos dinâmicos.

Dimensões e métricas permitidas nos segmentos.
Nem todas as dimensões e métricas podem ser usadas nos segmentos. Para ver quais dimensões e métricas são permitidas nos segmentos, acesse o Explorador de dimensões e métricas.

1. Seleção de usuários x sessões

Especifique se você está tentando selecionar usuários ou sessões (ou ambos).

  • Utilize users:: para selecionar usuários.
  • Utilize sessions:: para selecionar sessões.
  • Se as condições para users:: e sessions:: forem especificadas:
    1. As condições de usuário serão aplicadas primeiro para resultar nas sessões dos usuários correspondentes.
    2. As condições de sessão serão aplicadas somente às sessões resultantes da etapa 1.

Por exemplo:

  • Selecione os usuários que usaram o navegador Chrome em pelo menos uma das suas sessões.
    • users::condition::ga:browser==Chrome
  • Selecione as sessões em que o navegador Chrome foi usado.
    • sessions::condition::ga:browser==Chrome
  • Selecione as sessões de usuários na cidade de Londres que usaram o navegador Chrome em pelo menos uma sessão.
    • users::condition::ga:browser==Chrome;sessions::condition::ga:city==London

Consulte a seção conditionScope da Referência de sintaxe para ver detalhes sobre como selecionar usuários e sessões.

2. Uso de condições x sequências

Depois de determinar se você deseja segmentar usuários ou sessões, especifique uma ou mais condições e/ou sequências.

Condições

As condições utilizam o prefixo condition::. Por exemplo:

  • Selecione usuários de São Paulo que acessaram com o navegador Chrome.
    • users::condition::ga:city==London;ga:browser==Chrome

Sequências

As condições de sequência consistem em uma ou mais etapas, e cada etapa é definida por uma ou mais condições de dimensão/métrica.

Especifique as condições com base em sequência usando o prefixo sequence:: e os operadores seguido por (;–>>) ou seguido imediatamente por (;–>). Por exemplo:

  • Selecione usuários que primeiro usaram um computador e depois um dispositivo móvel. Como estamos segmentando usuários, a pesquisa inclui todas as sessões de um usuário e verifica se ele usou o computador em uma sessão, depois, dispositivo móvel em uma das sessões subsequentes.
    • users::sequence::ga:deviceCategory==desktop;->>ga:deviceCategory==mobile
  • Você também pode usar várias condições em cada etapa.
    • users::sequence::ga:deviceCategory==desktop;ga:operatingSystem==Windows->>ga:deviceCategory==mobile;ga:operatingSystem==Android
  • Você também pode combinar condições e sequências em um segmento usando um operador AND (isto é, ";").
    • users::condition::ga:totalEvents>10;sequence::ga:deviceCategory==desktop->>ga:deviceCategory==mobile

Consulte a seção conditionType da Referência de sintaxe para ver detalhes sobre condições simples e com base em sequência. Para exemplos adicionais, consulte as seções Condições e Sequências da Referência do recurso de segmentos.

3. Uso de escopos de métricas

O escopo de uma métrica estabelece o nível no qual ela será definida: HIT, SESSÃO ou USUÁRIO. Por exemplo, ga:pageviews e ga:transactions são métricas no nível de HIT, pois ocorrem em um hit, enquanto ga:sessionDuration e ga:bounces são métricas no nível da SESSÃO, pois há um valor único para elas por sessão. Do ponto de vista conceitual, USUÁRIO é o escopo de nível mais alto, e HIT é o escopo de nível mais baixo.

Também é possível informar os valores das métricas nos escopos superiores ao escopo principal. Por exemplo, ga:pageviews e ga:transactions podem ser informadas no nível da SESSÃO e do USUÁRIO. Para isso, basta adicioná-las a cada hit que ocorre para as sessões ou os usuários em questão.

Você pode especificar o escopo de cada condição de métrica, o que determinará o nível em que a condição será aplicada. Os escopos das métricas são especificados com o prefixo perUser::, perSession:: ou perHit::.

Por exemplo:

  • Selecione usuários que gastaram pelo menos R$ 10,00 em um website (isto é, o valor da vida útil de um usuário é de pelo menos R$ 10,00).
    users::condition::perUser::ga:transactionRevenue>=10
    
  • Selecione usuários que gastaram pelo menos R$ 10,00 em uma sessão.
    users::condition::perSession::ga:transactionRevenue>=10
    

Restrições do escopo

A API de relatórios principais realiza a validação de escopos de métricas para garantir que a consulta realizada seja válida. As regras para validação de escopo são:

  1. O escopo especificado da métrica sempre precisa ser igual ou menor que o escopo da condição pai (conforme indicado pelo prefixo users:: ou sessions::).
  2. O escopo especificado da métrica precisa ser igual ou maior que seu escopo principal, conforme definido no modelo de dados. Consulte Métricas: referência de escopo principal para ver uma lista completa de métricas e seus escopos principais.

Por exemplo, os itens a seguir são escopos de métrica válidos:

  • Os escopos de métrica e condição são iguais (isto é, no nível do USUÁRIO).
    • users::condition::perUser::ga:transactionRevenue>10
  • O escopo da condição é maior que o escopo da métrica (isto é, USUÁRIO > SESSÃO).
    • users::condition::perSession::ga:transactionRevenue>10
  • ga:totalEvents é uma métrica de nível do HIT e, portanto, os escopos possíveis para ela em uma condição são perHit::, perSession:: ou perUser:: (pois todos eles são maiores ou iguais ao escopo no nível do HIT).
    • users::condition::perHit::ga:totalEvents>5
    • users::condition::perSession::ga:totalEvents>5

Por exemplo, os itens a seguir são escopos de métrica inválidos:

  • Este segmento é inválido, pois o escopo da condição pai é menor que o escopo da métrica (isto é, SESSÃO < USUÁRIO).
    • sessions::condition::perUser::ga:transactionRevenue>10
  • Usar um escopo no nível do HIT para uma métrica no nível da SESSÃO e um nível do HIT < nível da SESSÃO.
    • users::condition::perHit::ga:sessionDuration>60

Escopo padrão

Quando um escopo de condição da métrica não é especificado de forma explícita, o escopo da condição é aplicado como padrão. Por exemplo, o segmento abaixo usará um escopo no nível do USUÁRIO para todas as suas condições de métrica:users::condition::ga:transactionRevenue>=10;ga:sessionDuration>60

Referência de sintaxe de segmentos dinâmicos

Sintaxe básica

A sintaxe para definir um segmento tem este formato: segment=<segmentCondition>+. Em outras palavras, um segmento é composto por uma ou mais declarações de segmentCondition.

Uma <segmentCondition> é definida como: <conditionScope><conditionType><dimensionOrMetricConditions>

Em que:
conditionScope especifica o escopo de nível superior das condições.
conditionType especifica o tipo de condição.
dimensionOrMetricConditions especifica as condições de dimensão/métrica ou as etapas da sequência.

conditionScope

Especifica o escopo de nível superior das condições. Os valores possíveis são:

  • users:: para selecionar usuários.
  • sessions:: para selecionar sessões.

Restrições e considerações associadas a conditionScope:

  • Se várias condições de "usuários" e "sessões" forem especificadas em um único segmento, será necessário combiná-las com um operador E.
  • As condições que selecionarem usuários e sessões também precisarão ser combinadas com um operador E. Quando forem especificadas condições para usuários e sessões, todas as condições de usuário serão aplicadas primeiro para encontrar os usuários correspondentes. Em seguida, todas as condições de sessão serão aplicadas às sessões que pertencem a esses usuários.
  • Se você estiver usando condições no nível do usuário, o período precisará ser inferior a 90 dias.
  • O escopo da condição também determina o nível de escopo padrão de todas as condições de métrica abaixo dele. Consulte Métricas: Referência de escopo principal para mais detalhes sobre os níveis de escopo.

conditionType

Especifica o tipo de condição. Os valores possíveis são:

  • condition:: para especificar condições simples (isto é, que não se baseiam em sequências).
  • sequence:: para especificar condições que se baseiam em sequências.

Restrições e considerações associadas a conditionType:

  • Se várias "condições simples" e "sequências" forem especificadas, elas sempre precisarão ser combinadas com um operador E
  • É permitido usar no máximo 10 etapas de condições com base em sequência por segmento.

Condições simples

As condições simples consistem em uma ou mais condições de dimensão/métrica que podem ser combinadas.

Os operadores válidos para condições simples são:

A sintaxe das condições simples é:

condition::<dimensionOrMetricConditions>

Exemplo de condição simples:

  • users::condition::ga:transactionRevenue>10;ga:sessionDuration>60
  • É possível especificar um operador de negação de nível superior para encontrar o complemento de uma determinada condição simples que pode conter várias condições de dimensão/métrica. Por exemplo, users::condition::!ga:transactionRevenue>10;ga:sessionDuration>60

Condições de exclusão

Uma condição de exclusão é usada para criar um segmento que não atende à condição definida.

A sintaxe usa o operador NOT (o caractere !) para negar uma condição e excluir as sessões que correspondem a ela.

Exclua sessões em que a página de saída corresponde exatamente ao caminho da página raiz:
sessions::condition::!ga:exitPagePath==/

Várias condições

Você pode agrupar todas as condições no nível do usuário em um único prefixo users:: ou usar um prefixo users:: separado para cada condição. O mesmo vale para as condições no nível da sessão.

Por exemplo, os segmentos a seguir são equivalentes. Em ambos os casos, condition1 e condition2 recebem o operador E para selecionar usuários:
users::<condition1>;<condition2>
users::<condition1>users::<condition2>

Condições de sequência

As condições de sequência consistem em uma ou mais etapas, e cada etapa é definida por uma ou mais condições de dimensão/métrica. É possível combinar várias etapas com operadores de sequência especiais.

Os operadores de sequência válidos para condições de sequência são:

  • O operador –>> indica que a etapa anterior antecede a próxima etapa.
  • O operador –> indica que a etapa anterior antecede imediatamente a próxima etapa.

A sintaxe das condições de sequência é:

sequence:: NOT? FIRST_HIT_MATCHES_FIRST_STEP? (AND (PRECEDES|IMMEDIATELY_PRECEDES) <step>)*

Em que:

NOT é representado por: !
FIRST_HIT_MATCHES_FIRST_STEP é representado: ^
PRECEDES é representado por: ;–>>
IMMEDIATELY_PRECEDES é representado por: ;–>
step é representado por: <dimensionOrMetricConditions>

Exemplo de condições da sequência:

  • users::sequence::ga:deviceCategory==desktop;->ga:deviceCategory==tablet
  • Também é possível especificar um operador de negação de nível superior para encontrar o complemento de uma determinada sequência que pode conter várias etapas e/ou condições de dimensão/métrica. Por exemplo, users::sequence::!ga:deviceCategory==desktop;->ga:deviceCategory==tablet
  • O operador ^ pode ser usado para especificar que a primeira etapa corresponde ao primeiro hit da primeira sessão no período especificado. Por exemplo, users::sequence::^ga:deviceCategory==desktop;->ga:deviceCategory==tablet

Condições de data da sessão

Os segmentos são compatíveis com um tipo de análise que utiliza a sintaxe dateOfSession. Em combinação com o operador "entre" <>, você pode restringir um segmento a um grupo de usuários que iniciaram uma sessão e um determinado período. O período máximo para dateOfSession é de 31 dias. Consulte o exemplo de data da sessão abaixo para detalhes sobre seu uso.

Condições de dimensão e métrica

Combinação de condições

Você pode combinar uma ou mais condições de dimensão usando os operadores E (isto é, ";") e OU (isto é, ",") com prioridade para o operador OU.

A sintaxe é a mesma que foi usada para combinar filtros. Consulte Combinação de filtros na API de relatórios principais para ver detalhes.

Operadores

A tabela a seguir descreve todos os operadores disponíveis que podem ser usados nos segmentos e se eles são compatíveis com dimensões e/ou métricas.

Operador Descrição Compatível com as condições de dimensão? Compatível com as condições de métricas?
== Corresponde exatamente ou é igual. Sim
Ex.: ga:city==London
Sim
Ex.: ga:adCost==10
!= Não corresponde exatamente ou não é igual. Sim
Ex.: ga:city!=London
Sim
Ex.: ga:adCost!=10
< Menor que. Sim (apenas para valores numéricos).
Ex.: ga:hour<12
Sim
Ex.: ga:adCost<10
<= Menor ou igual a Sim (apenas para valores numéricos).
Ex.: ga:hour<=12
Sim
Ex.: ga:adCost<=10
> Maior que. Sim (apenas para valores numéricos).
Ex.: ga:hour>12
Sim
Ex.: ga:adCost>10
>= Maior ou igual a Sim (apenas para valores numéricos).
Ex.: ga:hour>=12
Sim
Ex.: ga:adCost>=10
<> Entre (o valor está entre um intervalo determinado).1 Sim (apenas para valores numéricos).
Ex.: ga:hour<>1_12
Sim
Ex.: ga:adCost<>10_20
[] Na lista (o valor é um dos valores listados).2 Sim
Ex.: ga:browser[]Chrome|Firefox|Opera
Não
=@ Contém substring. Sim
Ex.: ga:keyword=@shoes
Não
!@ Não contém substring. Sim
Ex.: ga:keyword!@shoes
Não
=~ Contém uma correspondência de uma expressão regular. Sim
Ex.: ga:keyword=~shoes
Não
!~ Não contém uma correspondência de uma expressão regular. Sim
Ex.: ga:keyword!~shoes
Não

1Operador "entre" <>
Permite consultar valores de um determinado intervalo. Os valores do intervalo são inclusivos e podem ser usados para métricas e dimensões que possuem valores numéricos (por exemplo, ga:hour). É necessário separar os valores mín. e máx. no intervalo com um sublinhado.

Sintaxe:
{dimensionOrMetricName}<>{minValue}_{maxValue}

Exemplo:
Selecione as sessões que ocorreram das 12h00 às 23h00.
sessions::condition::ga:hour<>12_23

2Operador "na lista" []
Permite consultar valores de uma determinada lista. É possível utilizá-lo somente com dimensões. Use um caractere "|" para separar a lista de valores. Se houver um "|" no valor, é necessário escapá-lo.

Sintaxe:
{dimensionName}[]{value1}|{value2}|...

Restrições:
É permitido usar no máximo 10 valores por condição de dimensão na lista (por exemplo, ga:city[]city1|city2|...|city10).

Exemplo:
Selecione sessões que ocorreram no navegador Chrome, Firefox ou Opera.
sessions::condition::ga:browser[]Chrome|Firefox|Opera

Como escapar caracteres especiais

Será necessário escapar os caracteres especiais "," e ";" se eles ocorrerem nas expressões de valor. Por exemplo, ga:keyword==nike\,shoes

Para detalhes adicionais sobre as condições de dimensão e métrica, consulte a Referência da API de relatórios principais.

Restrições

As restrições relacionadas às condições de dimensão e métrica são:

  • É permitido usar no máximo 10 condições de dimensão ou métrica por segmento.
  • O tamanho máximo da expressão das condições de dimensão é 1.024 caracteres.

Migração de segmentos dinâmicos legados

Os segmentos dinâmicos legados que usam o prefixo dynamic:: são equivalentes aos segmentos no nível da sessão com condições de dimensão e métrica na sintaxe atual. Se você utiliza segmentos dinâmicos legados, deve migrar para a nova sintaxe substituindo o prefixo dynamic:: pelo prefixo sessions::condition::. Por exemplo, os dois segmentos abaixo são equivalentes:

dynamic::ga:browser==Chrome
é igual a:
sessions::condition::ga:browser==Chrome

Exemplos de segmento

1. Informações demográficas: Homens que falam inglês (EUA), têm interesse em jogos e são naturais das Américas.

Os segmentos com base no usuário são aplicados primeiro. Desse modo, a condição com base no usuário retorna usuários do sexo masculino que têm interesse em jogos. As sessões pertencentes a esses usuários são, então, sujeitas às condições com base na sessão, o que retorna sessões originadas das Américas e que estavam no idioma inglês (EUA).

users::condition::ga:userGender==Male;users::condition::ga:interestAffinityCategory==Games ; sessions::condition::ga:region==Americas;sessions::condition::ga:language==en-u

2. Comportamento: Usuários que tiveram > 100 sessões, não acessaram o site nos últimos 7 dias, realizaram > 2 transações por sessão e passaram > 100 segundos no site por sessão.

users::condition::ga:sessions>100;ga:daysSinceLastSession>=7; perSession::ga:transactions>2;perSession::ga:sessionDuration>100

3. Sessões: Selecione sessões que ocorreram no navegador Chrome, nos EUA e que tiveram > 1 exceção por hit E usuários que tiveram < 2 saídas por sessão.

sessions::condition::ga:browser==Chrome;ga:country==US;perHit::ga:exceptions>1; users::condition::perSession::ga:exits<2

4. Sessão com uma sequência: Selecione sessões com "Etapa: Chrome e total de eventos por hit > 5" E usuários com "Etapa: no computador" seguida por "Etapa: em dispositivos móveis".

sessions::sequence::ga:browser==Chrome;condition::perHit::ga:totalEvents>5;users::sequence::ga:deviceCategory==desktop->>ga:deviceCategory=mobile

5. Data da sessão: Selecione usuários que tiveram sua primeira sessão entre 20 de maio de 2014 e 30 de maio de 2014 e que passaram > 600 segundos no site.

users::sequence::^ga:sessionCount==1;dateOfSession<>2014-05-20_2014-05-30;->>ga:sessionDurationBucket>600

Métricas: Referência de escopo principal

Métrica Escopo principal
ga:adClicksHIT
ga:adCostHIT
ga:adsenseAdsClicksHIT
ga:adsenseAdsViewedHIT
ga:adsenseAdUnitsViewedHIT
ga:adsenseCTRHIT
ga:adsenseECPMHIT
ga:adsensePageImpressionsHIT
ga:adsenseRevenueHIT
ga:avgDomainLookupTimeHIT
ga:avgDomContentLoadedTimeHIT
ga:avgDomInteractiveTimeHIT
ga:avgEventValueHIT
ga:avgPageDownloadTimeHIT
ga:avgPageLoadTimeHIT
ga:avgRedirectionTimeHIT
ga:avgScreenviewDurationHIT
ga:avgSearchDepthHIT
ga:avgSearchDurationHIT
ga:avgSearchResultViewsHIT
ga:avgServerConnectionTimeHIT
ga:avgServerResponseTimeHIT
ga:avgUserTimingValueHIT
ga:costPerConversionHIT
ga:costPerGoalConversionHIT
ga:costPerTransactionHIT
ga:CPCHIT
ga:CPMHIT
ga:CTRHIT
ga:domainLookupTimeHIT
ga:domContentLoadedTimeHIT
ga:domInteractiveTimeHIT
ga:domLatencyMetricsSampleHIT
ga:eventValueHIT
ga:exceptionsHIT
ga:exceptionsPerScreenviewHIT
ga:fatalExceptionsHIT
ga:fatalExceptionsPerScreenviewHIT
ga:goalAbandonRateAllHIT
ga:goalAbandonsAllHIT
ga:goalCompletionsAllHIT
ga:goalStartsAllHIT
ga:goalValueAllHIT
ga:goalValueAllPerSearchHIT
ga:goalXXAbandonRateHIT
ga:goalXXAbandonsHIT
ga:goalXXCompletionsHIT
ga:goalXXStartsHIT
ga:goalXXValueHIT
ga:impressionsHIT
ga:itemQuantityHIT
ga:itemRevenueHIT
ga:itemsPerPurchaseHIT
ga:localItemRevenueHIT
ga:localTransactionRevenueHIT
ga:localTransactionShippingHIT
ga:localTransactionTaxHIT
ga:marginHIT
ga:metricXXHIT
ga:pageDownloadTimeHIT
ga:pageLoadSampleHIT
ga:pageLoadTimeHIT
ga:pageValueHIT
ga:pageviewsHIT
ga:percentSearchRefinementsHIT
ga:redirectionTimeHIT
ga:revenuePerItemHIT
ga:revenuePerTransactionHIT
ga:ROIHIT
ga:RPCHIT
ga:screenviewsHIT
ga:searchDepthHIT
ga:searchDurationHIT
ga:searchGoalConversionRateAllHIT
ga:searchGoalXXConversionRateHIT
ga:searchRefinementsHIT
ga:searchResultViewsHIT
ga:searchUniquesHIT
ga:serverConnectionTimeHIT
ga:serverResponseTimeHIT
ga:socialActivitiesHIT
ga:socialInteractionsHIT
ga:socialInteractionsPerSessionHIT
ga:speedMetricsSampleHIT
ga:timeOnScreenHIT
ga:totalEventsHIT
ga:totalValueHIT
ga:transactionRevenueHIT
ga:transactionsHIT
ga:transactionShippingHIT
ga:transactionTaxHIT
ga:uniqueAppviewsHIT
ga:uniqueEventsHIT
ga:uniquePageviewsHIT
ga:uniquePurchasesHIT
ga:uniqueScreenviewsHIT
ga:uniqueSocialInteractionsHIT
ga:userTimingSampleHIT
ga:userTimingValueHIT
ga:adsenseExitsSESSÃO
ga:avgTimeOnPageSESSÃO
ga:avgSessionDurationSESSÃO
ga:bouncesSESSÃO
ga:entranceBounceRateSESSÃO
ga:entranceRateSESSÃO
ga:entrancesSESSÃO
ga:eventsPerSessionWithEventSESSÃO
ga:exitRateSESSÃO
ga:exitsSESSÃO
ga:goalConversionRateAllSESSÃO
ga:goalValuePerSessionSESSÃO
ga:goalXXConversionRateSESSÃO
ga:organicSearchesSESSÃO
ga:pageviewsPerSessionSESSÃO
ga:percentSessionsWithSearchSESSÃO
ga:screenviewsPerSessionSESSÃO
ga:searchExitRateSESSÃO
ga:searchExitsSESSÃO
ga:searchSessionsSESSÃO
ga:sessionDurationSESSÃO
ga:transactionRevenuePerSessionSESSÃO
ga:transactionsPerSessionSESSÃO
ga:bounceRateSESSÃO
ga:sessionsSESSÃO
ga:sessionsWithEventSESSÃO
ga:newSessionsUSUÁRIO
ga:percentNewSessionsUSUÁRIO
ga:usersUSUÁRIO