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:
- Segmentos por ID: consulte usando o ID numérico de um segmento integrado ou personalizado.
- 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:
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::
esessions::
forem especificadas:- As condições de usuário serão aplicadas primeiro para resultar nas sessões dos usuários correspondentes.
- 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 São Paulo que usaram o navegador Chrome em pelo menos uma sessão.
users::condition::ga:browser==Chrome;sessions::condition::ga:city==London
Veja a seção conditionScope da Referência de sintaxe para detalhes sobre como selecionar usuários e sessões.
2. Uso de condições x sequências
Depois de determinar se você quer 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 Londres 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 e depois um 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 E (isto é, ‘;’).
-
users::condition::ga:totalEvents>10;sequence::ga:deviceCategory==desktop->>ga:deviceCategory==mobile
-
Consulte a seção conditionType da Referência de sintaxe para 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:
- O escopo especificado da métrica sempre precisa ser igual ou menor que o escopo da condição pai (conforme indicado pelo prefixo
users::
ousessions::
). - 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ãoperHit::
,perSession::
ouperUser::
(porque 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:
- Combinação de condições com operadores E ou OU.
- Operadores de dimensão e métrica.
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?
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 Por exemplo: ga:city!=London |
Sim Por exemplo: ga:adCost!=10 |
< |
Menor que. | Sim (apenas para valores numéricos). Ex.: ga:hour<12 |
Sim Ex.: ga:adCost<10 |
<= |
Menor ou igual. | 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. | 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 Por exemplo: 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 Por exemplo: 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 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 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:adClicks | HIT |
ga:adCost | HIT |
ga:adsenseAdsClicks | HIT |
ga:adsenseAdsViewed | HIT |
ga:adsenseAdUnitsViewed | HIT |
ga:adsenseCTR | HIT |
ga:adsenseECPM | HIT |
ga:adsensePageImpressions | HIT |
ga:adsenseRevenue | HIT |
ga:avgDomainLookupTime | HIT |
ga:avgDomContentLoadedTime | HIT |
ga:avgDomInteractiveTime | HIT |
ga:avgEventValue | HIT |
ga:avgPageDownloadTime | HIT |
ga:avgPageLoadTime | HIT |
ga:avgRedirectionTime | HIT |
ga:avgScreenviewDuration | HIT |
ga:avgSearchDepth | HIT |
ga:avgSearchDuration | HIT |
ga:avgSearchResultViews | HIT |
ga:avgServerConnectionTime | HIT |
ga:avgServerResponseTime | HIT |
ga:avgUserTimingValue | HIT |
ga:costPerConversion | HIT |
ga:costPerGoalConversion | HIT |
ga:costPerTransaction | HIT |
ga:CPC | HIT |
ga:CPM | HIT |
ga:CTR | HIT |
ga:domainLookupTime | HIT |
ga:domContentLoadedTime | HIT |
ga:domInteractiveTime | HIT |
ga:domLatencyMetricsSample | HIT |
ga:eventValue | HIT |
ga:exceptions | HIT |
ga:exceptionsPerScreenview | HIT |
ga:fatalExceptions | HIT |
ga:fatalExceptionsPerScreenview | HIT |
ga:goalAbandonRateAll | HIT |
ga:goalAbandonsAll | HIT |
ga:goalCompletionsAll | HIT |
ga:goalStartsAll | HIT |
ga:goalValueAll | HIT |
ga:goalValueAllPerSearch | HIT |
ga:goalXXAbandonRate | HIT |
ga:goalXXAbandons | HIT |
ga:goalXXCompletions | HIT |
ga:goalXXStarts | HIT |
ga:goalXXValue | HIT |
ga:impressions | HIT |
ga:itemQuantity | HIT |
ga:itemRevenue | HIT |
ga:itemsPerPurchase | HIT |
ga:localItemRevenue | HIT |
ga:localTransactionRevenue | HIT |
ga:localTransactionShipping | HIT |
ga:localTransactionTax | HIT |
ga:margin | HIT |
ga:metricXX | HIT |
ga:pageDownloadTime | HIT |
ga:pageLoadSample | HIT |
ga:pageLoadTime | HIT |
ga:pageValue | HIT |
ga:pageviews | HIT |
ga:percentSearchRefinements | HIT |
ga:redirectionTime | HIT |
ga:revenuePerItem | HIT |
ga:revenuePerTransaction | HIT |
ga:ROI | HIT |
ga:RPC | HIT |
ga:screenviews | HIT |
ga:searchDepth | HIT |
ga:searchDuration | HIT |
ga:searchGoalConversionRateAll | HIT |
ga:searchGoalXXConversionRate | HIT |
ga:searchRefinements | HIT |
ga:searchResultViews | HIT |
ga:searchUniques | HIT |
ga:serverConnectionTime | HIT |
ga:serverResponseTime | HIT |
ga:socialActivities | HIT |
ga:socialInteractions | HIT |
ga:socialInteractionsPerSession | HIT |
ga:speedMetricsSample | HIT |
ga:timeOnScreen | HIT |
ga:totalEvents | HIT |
ga:totalValue | HIT |
ga:transactionRevenue | HIT |
ga:transactions | HIT |
ga:transactionShipping | HIT |
ga:transactionTax | HIT |
ga:uniqueAppviews | HIT |
ga:uniqueEvents | HIT |
ga:uniquePageviews | HIT |
ga:uniquePurchases | HIT |
ga:uniqueScreenviews | HIT |
ga:uniqueSocialInteractions | HIT |
ga:userTimingSample | HIT |
ga:userTimingValue | HIT |
ga:adsenseExits | SESSÃO |
ga:avgTimeOnPage | SESSÃO |
ga:avgSessionDuration | SESSÃO |
ga:bounces | SESSÃO |
ga:entranceBounceRate | SESSÃO |
ga:entranceRate | SESSÃO |
ga:entrances | SESSÃO |
ga:eventsPerSessionWithEvent | SESSÃO |
ga:exitRate | SESSÃO |
ga:exits | SESSÃO |
ga:goalConversionRateAll | SESSÃO |
ga:goalValuePerSession | SESSÃO |
ga:goalXXConversionRate | SESSÃO |
ga:organicSearches | SESSÃO |
ga:pageviewsPerSession | SESSÃO |
ga:percentSessionsWithSearch | SESSÃO |
ga:screenviewsPerSession | SESSÃO |
ga:searchExitRate | SESSÃO |
ga:searchExits | SESSÃO |
ga:searchSessions | SESSÃO |
ga:sessionDuration | SESSÃO |
ga:transactionRevenuePerSession | SESSÃO |
ga:transactionsPerSession | SESSÃO |
ga:bounceRate | SESSÃO |
ga:sessions | SESSÃO |
ga:sessionsWithEvent | SESSÃO |
ga:newSessions | USER |
ga:percentNewSessions | USER |
ga:users | USER |