API Core Reporting - Segmenti

Questo documento descrive la sintassi e le considerazioni per l'utilizzo dei segmenti nell'API Core Reporting.

Introduzione

Quando utilizzi la funzionalità di segmentazione dell'API di reporting principale, puoi richiedere un segmento nell'API di reporting principale in due modi:

1. Segmenti per ID: esegui una query che utilizza l'ID numerico di un segmento integrato o personalizzato.
2. Segmenti dinamici. Specifica il segmento in modo dinamico al momento della richiesta.

Segmenti per ID

Puoi richiedere un segmento nell'API di reporting principale utilizzando l'ID di un segmento integrato o personalizzato. Tutti i segmenti disponibili per un utente possono essere recuperati con il metodo list della raccolta dei segmenti nell'API di gestione di Google Analytics. Per ogni segmento, l'ID è disponibile nella proprietà id della risorsa Segmento.

Per saperne di più sull'utilizzo degli ID segmento nelle richieste API, consulta la documentazione sull'API di reporting principale.

Segmenti dinamici

Puoi anche creare e utilizzare un segmento in modo dinamico quando effettui una richiesta API. In genere, durante la creazione di un segmento dinamico devi prendere in considerazione quanto segue:

1. Selezione degli utenti e delle sessioni
2. Utilizzo di condizioni e sequenze
3. Utilizzo degli ambiti delle metriche

Di seguito viene descritta a un livello generale ogni considerazione necessaria per creare un segmento dinamico. Per esaminare la sintassi completa dei segmenti dinamici, consulta la pagina Riferimento per la sintassi dei segmenti dinamici.

Dimensioni e metriche consentite nei segmenti.
Non tutte le dimensioni e metriche possono essere utilizzate nei segmenti. Per esaminare le dimensioni e le metriche consentite nei segmenti, visita lo strumento di esplorazione di dimensioni e metriche.

1. Selezione di utenti e sessioni

Specifica se stai tentando di selezionare utenti o sessioni (o entrambi).

• Utilizza users:: per selezionare gli utenti.
• Usa sessions:: per selezionare le sessioni.
• Se vengono specificate le condizioni sia per users:: che per sessions:::
  1. Le condizioni utente vengono applicate prima per produrre le sessioni per gli utenti corrispondenti.
  2. vengono applicate solo alle sessioni dalla posizione 1.

Ad esempio:

• Seleziona gli utenti che hanno utilizzato il browser Chrome in almeno una delle sessioni.
  • users::condition::ga:browser==Chrome
• Seleziona le sessioni in cui è stato utilizzato il browser Chrome.
  • sessions::condition::ga:browser==Chrome
• Seleziona le sessioni della città di Londra dagli utenti che hanno eseguito almeno una sessione in cui è stato utilizzato il browser Chrome.
  • users::condition::ga:browser==Chrome;sessions::condition::ga:city==London

Consulta la sezione conditionScope del riferimento alla sintassi per i dettagli sulla selezione di utenti e sessioni.

2. Utilizzo di condizioni e sequenze

Dopo aver determinato se vuoi segmentare utenti o sessioni, devi specificare una o più condizioni e/o sequenze.

Condizioni

Le condizioni utilizzano il prefisso condition::. Ad esempio:

• Seleziona gli utenti di Londra che hanno visitato il sito utilizzando il browser Chrome.
  • users::condition::ga:city==London;ga:browser==Chrome

Sequenze

Le condizioni della sequenza sono composte da uno o più passaggi, in cui ogni passaggio è definito da una o più condizioni di dimensione/metrica.

Specifica le condizioni basate su sequenza utilizzando il prefisso sequence:: e gli operatori seguito da (;–>>) o seguito immediatamente da (;–>). Ad esempio:

• Seleziona gli utenti che hanno utilizzato per la prima volta un computer, seguito da un dispositivo mobile. Poiché gli utenti vengono segmentati, l'operazione esegue la ricerca in tutte le sessioni di un utente e verifica se un utente ha utilizzato un computer in una sessione, seguita da un dispositivo mobile in una delle sessioni successive.
  • users::sequence::ga:deviceCategory==desktop;->>ga:deviceCategory==mobile
• Puoi anche utilizzare più condizioni per ogni passaggio.
  • users::sequence::ga:deviceCategory==desktop;ga:operatingSystem==Windows->>ga:deviceCategory==mobile;ga:operatingSystem==Android
• Puoi anche combinare condizioni e sequenze in un segmento utilizzando un AND (ovvero ';').
  • users::condition::ga:totalEvents>10;sequence::ga:deviceCategory==desktop->>ga:deviceCategory==mobile

Consulta la sezione conditionType del riferimento alla sintassi per i dettagli sulle condizioni semplici e basate su sequenza. Per ulteriori esempi, consulta le sezioni Condizioni e Sequenze della pagina Riferimento alle funzionalità dei segmenti.

3. Utilizzo degli ambiti delle metriche

L'ambito di una metrica definisce il livello a cui viene definita: HIT, SESSION o USER. Ad esempio, ga:pageviews e ga:transactions sono metriche a livello di HIT poiché si verificano in un hit, mentre ga:sessionDuration e ga:bounces sono metriche a livello di SESSIONE poiché esiste un unico valore per ciascuna sessione. Concettualmente, USER è l'ambito di livello più alto e HIT è l'ambito di livello più basso.

I valori delle metriche possono essere inclusi nei report anche in ambiti superiori a quelli principali. ad esempio ga:pageviews e ga:transactions possono essere riportati a livello di SESSION e USER semplicemente sommandoli per ogni hit che si verifica in quelle sessioni o per quegli utenti.

Puoi specificare l'ambito per ogni condizione della metrica, il che determinerà il livello a cui viene applicata la condizione. Gli ambiti delle metriche vengono specificati utilizzando il prefisso perUser::, perSession:: o perHit::.

Ad esempio:

• Seleziona gli utenti che hanno speso almeno 10 € su un sito web (ad es. il lifetime value di un utente è pari ad almeno 10 €).

  users::condition::perUser::ga:transactionRevenue>=10
  

• Seleziona gli utenti che hanno speso almeno 10 € in una sessione.

  users::condition::perSession::ga:transactionRevenue>=10
  

Limitazioni dell'ambito

L'API Core Reporting esegue la convalida degli ambiti delle metriche per garantire che la query specificata sia valida. Le regole per la convalida dell'ambito sono:

1. L'ambito delle metriche specificato deve essere sempre uguale o inferiore all'ambito della condizione padre (come indicato dal prefisso users:: o sessions::).
2. L'ambito delle metriche specificato deve essere uguale o superiore all'ambito principale definito nel modello dei dati. Consulta Metriche: riferimento all'ambito principale per un elenco completo delle metriche e dei relativi ambiti principali.

Ad esempio, di seguito sono riportati ambiti delle metriche validi:

• Gli ambiti delle condizioni e delle metriche sono uguali (ad es. livello USER).
  • users::condition::perUser::ga:transactionRevenue>10
• L'ambito delle condizioni è superiore a quello delle metriche (ad es. UTENTE > SESSIONE).
  • users::condition::perSession::ga:transactionRevenue>10
• ga:totalEvents è una metrica a livello di HIT e di conseguenza i possibili ambiti per questa condizione in una condizione sono perHit::, perSession:: o perUser:: (dal momento che sono tutti maggiori o uguali all'ambito a livello di HIT).
  • users::condition::perHit::ga:totalEvents>5
  • users::condition::perSession::ga:totalEvents>5

Ad esempio, di seguito sono riportati ambiti delle metriche non validi:

• Il seguente segmento non è valido poiché l'ambito della condizione principale è inferiore a quello delle metriche (ad es. SESSIONE < UTENTE).
  • sessions::condition::perUser::ga:transactionRevenue>10
• Utilizzo di un ambito a livello HIT per una metrica a livello di SESSION e di un livello HIT < SESSION.
  • users::condition::perHit::ga:sessionDuration>60

Ambito predefinito

Quando non viene specificato esplicitamente un ambito per la condizione della metrica, per impostazione predefinita viene utilizzato l'ambito della condizione. Ad esempio, il seguente segmento utilizzerà un ambito a livello di UTENTE per tutte le condizioni delle metriche: users::condition::ga:transactionRevenue>=10;ga:sessionDuration>60

Riferimento per la sintassi dei segmenti dinamici

Sintassi di base

La sintassi per definire un segmento è nel formato: segment=<segmentCondition>+. In altre parole, un segmento è composto da una o più istruzioni segmentCondition.

Per <segmentCondition> si intende: <conditionScope><conditionType><dimensionOrMetricConditions>

dove:
conditionScope specifica l'ambito di primo livello delle condizioni.
conditionType specifica il tipo di condizioni.
dimensionOrMetricConditions specifica le condizioni di dimensione/metrica o i passaggi della sequenza.

conditionScope

Specifica l'ambito di primo livello delle condizioni. I valori possibili sono:

• users:: per la selezione degli utenti.
• sessions:: per la selezione delle sessioni.

Vincoli e considerazioni per conditionScope:

• Se in un singolo segmento sono specificate più condizioni "utenti" e "sessioni", devono essere combinate con un operatore AND.
• Le condizioni che selezionano sia utenti che sessioni devono essere combinate con un operatore AND. Quando sono specificate condizioni sia per gli utenti sia per le sessioni, tutte le condizioni utente vengono applicate per prime per trovare gli utenti corrispondenti, seguite da tutte le condizioni delle sessioni appartenenti agli utenti corrispondenti.
• Se utilizzi condizioni a livello di utente, l'intervallo di date non deve essere superiore a 90 giorni.
• L'ambito delle condizioni determina anche il livello di ambito predefinito per tutte le condizioni delle metriche di livello inferiore. Per ulteriori dettagli sui livelli di ambito, consulta Metriche: riferimento ambito principale.

conditionType

Specifica il tipo di condizioni. I valori possibili sono:

• condition:: per specificare condizioni semplici (ovvero non basate su sequenza).
• sequence:: per specificare condizioni basate su sequenza.

Vincoli e considerazioni per conditionType:

• Se vengono specificate più "condizioni semplici" e "sequenze", queste devono essere sempre combinate con un operatore AND.
• Per le condizioni basate su sequenza sono consentiti massimo 10 passaggi per segmento.

Condizioni semplici

Le condizioni semplici sono composte da una o più condizioni dimensione/metrica che possono essere combinate.

Gli operatori di condizione validi per condizioni semplici sono:

• Combinazione di condizioni con gli operatori AND o OR.
• Operatori di dimensioni e metriche.

La sintassi per le condizioni semplici è:

condition::<dimensionOrMetricConditions>

Esempi di condizioni semplici:

• users::condition::ga:transactionRevenue>10;ga:sessionDuration>60
• È possibile specificare un operatore di negazione di primo livello per trovare il complemento di una determinata condizione semplice che può avere più condizioni di dimensione/metrica. ad esempio users::condition::!ga:transactionRevenue>10;ga:sessionDuration>60

Esclusione di condizioni

Una condizione di esclusione viene utilizzata per creare un segmento che non soddisfa la condizione definita.

La sintassi utilizza l'operatore NOT (il carattere !) per negare una condizione ed escludere le sessioni che corrispondono a quella condizione.

Escludi le sessioni in cui la pagina di uscita corrisponde esattamente al percorso della pagina principale:
sessions::condition::!ga:exitPagePath==/

Più condizioni

Puoi raggruppare tutte le condizioni a livello di utente in un singolo prefisso users:: oppure utilizzare un prefisso users:: separato per ogni condizione. Lo stesso vale anche per le condizioni a livello di sessione.

Ad esempio, i seguenti segmenti sono equivalenti. In entrambi i casi, condition1 e condition2 sono AND per utenti selezionati:
users::<condition1>;<condition2>
users::<condition1>users::<condition2>

Condizioni di sequenza

Le condizioni di sequenza consistono in uno o più passaggi, in cui ogni passaggio è definito da una o più condizioni di dimensione/metrica. È possibile combinare più passaggi con operatori di sequenza speciali.

Gli operatori di sequenza validi per le condizioni di sequenza sono:

• L'operatore –>> indica che il passaggio precedente precede quello successivo.
• L'operatore –> indica che il passaggio precedente precedenti immediatamente quello successivo.

La sintassi per le condizioni della sequenza è:

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

dove:

Esempi di condizioni della sequenza:

• users::sequence::ga:deviceCategory==desktop;->ga:deviceCategory==tablet
• È possibile specificare anche un operatore di negazione di primo livello per trovare il complemento di una determinata sequenza che può avere più passaggi e/o condizioni di dimensione/metrica. ad esempio users::sequence::!ga:deviceCategory==desktop;->ga:deviceCategory==tablet
• Puoi utilizzare l'operatore ^ per specificare che il primo passaggio corrisponde al primo hit della prima sessione nell'intervallo di date specificato. ad esempio users::sequence::^ga:deviceCategory==desktop;->ga:deviceCategory==tablet

Data delle condizioni della sessione

I segmenti supportano un tipo di analisi che utilizza la sintassi dateOfSession. In combinazione con l'operatore tra <>, puoi limitare un segmento a un gruppo di utenti che hanno avviato una sessione in un determinato intervallo di date. L'intervallo di date massimo per dateOfSession è 31 giorni. Consulta l'esempio di data della sessione di seguito per i dettagli sul suo utilizzo.

Condizioni di dimensioni e metriche

Combinazione di condizioni

Puoi combinare una o più condizioni di dimensione con AND (ovvero ";") e OR (ad es. ",") con l'operatore OR con una precedenza più alta.

La sintassi è la stessa utilizzata per combinare i filtri. Per maggiori dettagli, consulta la sezione Combinazione dei filtri nel riferimento dell'API di reporting principale.

Operatori

La tabella seguente descrive tutti gli operatori disponibili che possono essere utilizzati nei segmenti e se sono supportati per le dimensioni e/o le metriche.

¹Tra operatore <>
Consente di eseguire query per valori compresi in un determinato intervallo. I valori dell'intervallo sono inclusivi e possono essere utilizzati sia per le metriche sia per le dimensioni che hanno valori numerici (ad es. ga:hour). I valori minimo e massimo dell'intervallo devono essere separati da un trattino basso.

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

Esempio:
seleziona le sessioni che si sono verificate tra le 12 e le 23.
sessions::condition::ga:hour<>12_23

²Operatore in elenco []
Consente di eseguire query sui valori di un elenco specifico. Può essere utilizzato solo con le dimensioni. L'elenco dei valori deve essere separato da un carattere "|". Se il valore contiene "|", devi utilizzare i caratteri di escape.

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

Vincoli:
È consentito un massimo di 10 valori per condizione di dimensione in elenco (ad es. ga:city[]city1|city2|...|city10).

Esempio:
Seleziona le sessioni provenienti dai browser Chrome, Firefox o Opera.
sessions::condition::ga:browser[]Chrome|Firefox|Opera

Futuro dai caratteri speciali

I caratteri speciali "," e ";" devono essere preceduti da caratteri di escape se si trovano all'interno delle espressioni di valori. ad esempio ga:keyword==nike\,shoes

Per ulteriori dettagli sulle condizioni di dimensioni e metriche, consulta la pagina Riferimento per l'API di reporting principale.

Vincoli

I vincoli relativi alle condizioni di dimensioni e metriche sono:

• Un massimo di 10 condizioni di dimensione o metrica per segmento.
• La lunghezza massima delle espressioni per le condizioni di dimensione è di 1024 caratteri.

Migrazione di segmenti dinamici precedenti

I segmenti dinamici precedenti che utilizzano il prefisso dynamic:: equivalgono ai segmenti a livello di sessione con condizioni di dimensioni e metriche nella sintassi attuale. Se utilizzi segmenti dinamici precedenti, devi eseguire la migrazione alla nuova sintassi sostituendo il prefisso dynamic:: con il prefisso sessions::condition::. Ad esempio, i due segmenti seguenti sono equivalenti:

dynamic::ga:browser==Chrome
è uguale a:
sessions::condition::ga:browser==Chrome

Esempi di segmenti

1. Dati demografici: la lingua per gli uomini è l'inglese americano, è interessata ai giochi e proviene dalle Americhe.

I segmenti basati sugli utenti vengono applicati per primi. Quindi, la condizione basata sull'utente restituisce gli utenti di sesso maschile interessati ai giochi. Le sessioni che appartengono a questi utenti sono quindi soggette a condizioni basate sulle sessioni per ottenere sessioni che provenivano dalle Americhe e la lingua era EN-US.

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

2. Comportamento: utenti che hanno avuto più di 100 sessioni, non hanno effettuato visite negli ultimi 7 giorni, hanno effettuato più di 2 transazioni per sessione e hanno trascorso più di 100 secondi sul sito per sessione.

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

3. Sessioni: seleziona le sessioni con il browser Chrome, il paese come Stati Uniti ed eccezioni per hit > 1 E seleziona gli utenti le cui uscite per sessione sono < 2.

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

4. Sessione con una sequenza: seleziona le sessioni con Passaggio: Chrome e totali eventi per hit > 5 E seleziona gli utenti con Passaggio: su computer seguito dal passaggio su dispositivo mobile.

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

5. Data della sessione: seleziona gli utenti che hanno avviato la loro prima sessione tra il 20 maggio 2014 e il 30 maggio 2014 e che hanno trascorso più di 600 secondi sul sito.

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

Metriche: riferimento all'ambito principale