Questo documento descrive diverse funzionalità avanzate dell'API Google Analytics Data v1. Per un riferimento dettagliato dell'API, consulta il Riferimento API.
Elencare le definizioni personalizzate e creare report
L'API di dati può creare report sulle dimensioni personalizzate e sulle metriche personalizzate registrate. Il metodo API Metadata può essere utilizzato per elencare i nomi API delle definizioni personalizzate registrate della proprietà. Questi nomi API possono essere utilizzati, ad esempio, nelle richieste di report al metodo runReport.
Le sezioni seguenti mostrano esempi per ogni tipo di definizione personalizzata. In questi esempi, sostituisci GA_PROPERTY_ID con il tuo ID proprietà.
Dimensioni personalizzate basate sugli eventi
Passaggio 1: esegui una query sul metodo API Metadata con l'ID proprietà.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata
Passaggio 2: individua nella risposta la dimensione personalizzata basata sugli eventi su cui vuoi creare i report. Se la dimensione non è presente, devi registrarla.
"dimensions": [
...
{
"apiName": "customEvent:achievement_id",
"uiName": "Achievement ID",
"description": "An event scoped custom dimension for your Analytics property."
},
...
],
Passaggio 3: includi la dimensione personalizzata in una richiesta di report. Di seguito è riportata una richiesta di esempio al metodo runReport.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
"dimensions": [{ "name": "customEvent:achievement_id" }],
"metrics": [{ "name": "eventCount" }]
}
Dimensioni personalizzate basate sugli utenti
Passaggio 1: esegui una query sul metodo API Metadata con l'ID proprietà.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata
Passaggio 2: individua nella risposta la dimensione personalizzata basata sugli utenti per cui vuoi creare report. Se la dimensione non è presente, devi registrarla.
"dimensions": [
...
{
"apiName": "customUser:last_level",
"uiName": "Last level",
"description": "A user property for your Analytics property."
},
...
],
Passaggio 3: includi la dimensione personalizzata in una richiesta di report. Di seguito è riportata una richiesta di esempio al metodo runReport.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"entity": { "propertyId": "GA_PROPERTY_ID" },
"dateRanges": [{ "startDate": "7daysAgo", "endDate": "yesterday" }],
"dimensions": [{ "name": "customUser:last_level" }],
"metrics": [{ "name": "activeUsers" }]
}
Metriche personalizzate con ambito evento
Passaggio 1: esegui una query sul metodo API Metadata con l'ID proprietà.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata
Passaggio 2: individua nella risposta la metrica personalizzata basata sugli eventi per cui vuoi creare report. Se la metrica non è presente, devi registrarla.
"metrics": [
...
{
"apiName": "customEvent:credits_spent",
"uiName": "Credits Spent",
"description": "An event scoped custom metric for your Analytics property.",
"type": "TYPE_STANDARD"
},
...
],
Passaggio 3: includi la metrica personalizzata in una richiesta di report. Di seguito è riportata una richiesta di esempio al metodo runReport.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
"dimensions": [{ "name": "eventName" }],
"metrics": [{ "name": "customEvent:credits_spent" }]
}
Metriche del tasso di eventi chiave per un singolo evento chiave
Passaggio 1: esegui una query sul metodo dell'API Metadata con l'ID proprietà.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata
Passaggio 2: trova la metrica Tasso di eventi chiave per un evento chiave per cui vuoi generare report dalla risposta. Se l'evento chiave non è presente, devi configurarlo.
"metrics": [
...
{
"apiName": "sessionKeyEventRate:add_to_cart",
"uiName": "Session key event rate for add_to_cart",
"description": "The percentage of sessions in which a specific key event was triggered",
},
...
],
Passaggio 3: includi la metrica sul tasso di eventi chiave in una richiesta di report. Di seguito è riportata una richiesta di esempio al metodo runReport.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
"dimensions": [{ "name": "eventName" }],
"metrics": [{ "name": "sessionKeyEventRate:add_to_cart" }]
}
Medie delle metriche personalizzate con ambito evento
Passaggio 1: esegui una query sul metodo API Metadata con l'ID proprietà.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata
Passaggio 2: individua nella risposta la metrica personalizzata basata sugli eventi di cui vuoi creare i report. Se la metrica non è presente, devi registrarla.
"metrics": [
...
{
"apiName": "averageCustomEvent:credits_spent",
"uiName": "Average Credits Spent",
"description": "The average of an event scoped custom metric for your Analytics property.",
"type": "TYPE_STANDARD"
},
...
],
Passaggio 3: includi la media della metrica personalizzata in una richiesta di report. Di seguito è riportata una richiesta di esempio al metodo runReport.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "2020-11-01", "endDate": "2020-11-10" }],
"dimensions": [{ "name": "eventName" }],
"metrics": [{ "name": "averageCustomEvent:credits_spent" }]
}
Esempi di report sulle coorti
I report sulle coorti creano una serie temporale di fidelizzazione utenti per la coorte. Per una documentazione dettagliata di ogni campo dell'API, consulta il riferimento REST per CohortSpec.
Crea un report sulle coorti
Ecco un report sulle coorti di esempio in cui:
- La coorte è costituita da utenti con un valore
firstSessionDatedi2020-12-01; questo valore è configurato dall'oggettocohorts. Le dimensioni e le metriche nella risposta del report si baseranno solo sugli utenti della coorte. - Il report sulle coorti mostrerà tre colonne, configurate dagli oggetti
dimensions e metrics.
- La dimensione
cohortè il nome della coorte. - La dimensione
cohortNthDayindica il numero di giorni trascorsi dal giorno2020-12-01. - La metrica
cohortActiveUsersindica il numero di utenti ancora attivi.
- La dimensione
- L'oggetto
cohortsRangespecifica che il report deve contenere i dati sugli eventi a partire da2020-12-01e fino a2020-12-06per questa coorte.- Quando viene utilizzata una granularità di
DAILY, si consiglia di utilizzare la dimensionecohortNthDayper garantire la coerenza.
- Quando viene utilizzata una granularità di
La richiesta di report per la coorte è:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"dimensions": [{ "name": "cohort" }, { "name": "cohortNthDay" }],
"metrics": [{ "name": "cohortActiveUsers" }],
"cohortSpec": {
"cohorts": [
{
"dimension": "firstSessionDate",
"dateRange": { "startDate": "2020-12-01", "endDate": "2020-12-01" }
}
],
"cohortsRange": {
"endOffset": 5,
"granularity": "DAILY"
}
},
}
Per questa richiesta, un esempio di risposta del report è:
{
"dimensionHeaders": [
{ "name": "cohort" }, { "name": "cohortNthDay" }
],
"metricHeaders": [
{ "name": "cohortActiveUsers", "type": "TYPE_INTEGER" }
],
"rows": [
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0000" }],
"metricValues": [{ "value": "293" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0001" }],
"metricValues": [{ "value": "143" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0002" }],
"metricValues": [{ "value": "123" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0003" }],
"metricValues": [{ "value": "92" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0005" }],
"metricValues": [{ "value": "86" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0004" }],
"metricValues": [{ "value": "83" }]
}
],
"metadata": {},
"rowCount": 6
}
In base alla risposta di questo report, di seguito è riportato un grafico per questo report sulle coorti. Un insight di questo report è che il calo maggiore di utenti attivi per questa coorte si verifica tra il primo e il secondo giorno.
Più coorti e frazione di fidelizzazione utenti
L'acquisizione e la fidelizzazione degli utenti sono modi per far crescere il tuo sito web o la tua app. I report sulle coorti si concentrano sulla fidelizzazione degli utenti. In questo esempio, il report mostra che questa proprietà ha migliorato la fidelizzazione utenti di 4 giorni del 10% nel corso di due settimane.
Per creare questo report, specifichiamo tre coorti: la prima con un firstSessionDate di 2020-11-02, la seconda con un firstSessionDate di 2020-11-09 e la terza con un firstSessionDate di 2020-11-16. Poiché il numero di utenti della tua proprietà sarà diverso per questi tre giorni, confrontiamo la metrica della frazione di fidelizzazione utenti della coorte di cohortActiveUsers/cohortTotalUsers anziché utilizzare la metrica diretta cohortActiveUsers.
La richiesta di report per queste coorti è:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"dimensions": [{ "name": "cohort" },{ "name": "cohortNthDay" }],
"metrics": [
{
"name": "cohortRetentionFraction",
"expression": "cohortActiveUsers/cohortTotalUsers"
}
],
"cohortSpec": {
"cohorts": [
{
"dimension": "firstSessionDate",
"dateRange": { "startDate": "2020-11-02", "endDate": "2020-11-02" }
},
{
"dimension": "firstSessionDate",
"dateRange": { "startDate": "2020-11-09", "endDate": "2020-11-09" }
},
{
"dimension": "firstSessionDate",
"dateRange": { "startDate": "2020-11-16", "endDate": "2020-11-16" }
}
],
"cohortsRange": {
"endOffset": 4,
"granularity": "DAILY"
}
},
}
Per questa richiesta, un esempio di risposta del report è:
{
"dimensionHeaders": [{ "name": "cohort" },{ "name": "cohortNthDay" }],
"metricHeaders": [{
"name": "cohortRetentionFraction",
"type": "TYPE_FLOAT"
}
],
"rows": [
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0000" }],
"metricValues": [{ "value": "1" }]
},
{
"dimensionValues": [{ "value": "cohort_1" },{ "value": "0000" }],
"metricValues": [{ "value": "1" }]
},
{
"dimensionValues": [{ "value": "cohort_2" },{ "value": "0000" }],
"metricValues": [{ "value": "1" }]
},
{
"dimensionValues": [{ "value": "cohort_2" },{ "value": "0001" }],
"metricValues": [{ "value": "0.308" }]
},
{
"dimensionValues": [{ "value": "cohort_1" },{ "value": "0001" }],
"metricValues": [{ "value": "0.272" }]
},
{
"dimensionValues": [{ "value": "cohort_2" },{ "value": "0002" }],
"metricValues": [{ "value": "0.257" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0001" }],
"metricValues": [{ "value": "0.248" }]
},
{
"dimensionValues": [{ "value": "cohort_2" },{ "value": "0003" }],
"metricValues": [{ "value": "0.235" }]
},
{
"dimensionValues": [{ "value": "cohort_2" },{ "value": "0004" }],
"metricValues": [{ "value": "0.211" }]
},
{
"dimensionValues": [{ "value": "cohort_1" },{ "value": "0002" }],
"metricValues": [{ "value": "0.198" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0002" }],
"metricValues": [{ "value": "0.172" }]
},
{
"dimensionValues": [{ "value": "cohort_1" },{ "value": "0003" }],
"metricValues": [{ "value": "0.167" }]
},
{
"dimensionValues": [{ "value": "cohort_1" },{ "value": "0004" }],
"metricValues": [{ "value": "0.155" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0003" }],
"metricValues": [{ "value": "0.141" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0004" }],
"metricValues": [{ "value": "0.118" }]
}
],
"metadata": {},
"rowCount": 15
}
In base alla risposta di questo report, di seguito è riportato un grafico per questo report sulle coorti. Un insight di questo report è che la fidelizzazione utenti di 4 giorni è aumentata del 10% nel corso di due settimane. La coorte successiva con firstSessionDate di 2020-11-16 supera la fidelizzazione della coorte precedente con firstSessionDate di 2020-11-02.
Coorti settimanali e utilizzo delle coorti con altre funzionalità dell'API
Per rimuovere la variazione giornaliera nel comportamento degli utenti, utilizza le coorti settimanali. Nei report sulle coorti settimanali, tutti gli utenti con firstSessionDate nella stessa settimana formano la coorte. Le settimane iniziano di domenica e terminano di sabato. Inoltre, in questo report, suddividiamo la coorte per confrontare gli utenti con attività in Russia con quelli con attività in Messico. Questa suddivisione utilizza la dimensione country e un
dimensionFilter per considerare solo i due paesi.
La richiesta di report per queste coorti è:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"dimensions": [
{ "name": "cohort" },
{ "name": "cohortNthWeek" },
{ "name": "country" }
],
"metrics": [{ "name": "cohortActiveUsers" }],
"dimensionFilter": {
"filter": {
"fieldName": "country",
"inListFilter": {
"values": [ "Russia", "Mexico" ]
}
}
},
"cohortSpec": {
"cohorts": [
{
"dimension": "firstSessionDate",
"dateRange": {
"startDate": "2020-10-04",
"endDate": "2020-10-10"
}
}
],
"cohortsRange": {
"endOffset": 5,
"granularity": "WEEKLY"
}
},
}
Per questa richiesta, un esempio di risposta del report è:
{
"dimensionHeaders": [
{ "name": "cohort" },
{ "name": "cohortNthWeek" },
{ "name": "country" }
],
"metricHeaders": [
{ "name": "cohortActiveUsers", "type": "TYPE_INTEGER" }
],
"rows": [
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0000" },{ "value": "Russia" }
],
"metricValues": [{ "value": "105" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0000" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "98" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0001" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "35" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0002" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "24" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0001" },{ "value": "Russia" }
],
"metricValues": [{ "value": "23" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0004" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "17" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0003" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "15" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0005" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "15" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0002" },{ "value": "Russia" }
],
"metricValues": [{ "value": "3" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0003" },{ "value": "Russia" }
],
"metricValues": [{ "value": "1" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0004" },{ "value": "Russia" }
],
"metricValues": [{ "value": "1" }]
}
],
"metadata": {},
"rowCount": 11
}
Di seguito è riportato un grafico del report sulle coorti basato sulla risposta del report. In base a questo report, questa proprietà fidelizza meglio gli utenti con attività in Messico rispetto a quelli con attività in Russia.
Confronti
I confronti ti consentono di analizzare i sottoinsiemi dei tuoi dati uno accanto all'altro. Puoi definire i confronti specificando il campo comparisons in una definizione del report. La funzionalità per i confronti dell'API di dati è simile ai confronti nel frontend di Google Analytics.
Per la documentazione dettagliata di ogni campo dell'API, consulta il riferimento REST per Comparison.
Crea un confronto
Puoi creare un confronto distinto per ogni set di dati da confrontare. Ad esempio, per confrontare i dati dell'app e del web, puoi creare un confronto per i dati Android e iOS e un altro per i dati web.
Ecco un report di esempio che definisce due confronti e restituisce gli utenti attivi suddivisi per paese.
Il primo confronto, denominato "Traffico app", utilizza inListFilter per far corrispondere la dimensione platform ai valori "iOS" e "Android". Il secondo confronto denominato "Traffico web" utilizza stringFilter per trovare la corrispondenza tra la dimensione platform e "web".
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"comparisons": [
{
"name": "App traffic",
"dimensionFilter": {
"filter": {
"fieldName": "platform",
"inListFilter": {
"values": [
"iOS",
"Android"
]
}
}
}
},
{
"name": "Web traffic",
"dimensionFilter": {
"filter": {
"fieldName": "platform",
"stringFilter": {
"matchType": "EXACT",
"value": "web"
}
}
}
}
],
"dateRanges": [
{
"startDate": "2024-05-01",
"endDate": "2024-05-15"
}
],
"dimensions": [
{
"name": "country"
}
],
"metrics": [
{
"name": "activeUsers"
}
]
}
Per tutte le richieste che utilizzano la funzionalità di confronto, il campo comparison viene aggiunto automaticamente al report generato. Questo campo contiene il nome del confronto fornito nella richiesta.
Ecco uno snippet di esempio di una risposta contenente confronti:
{
"dimensionHeaders": [
{
"name": "comparison"
},
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "Web traffic"
},
{
"value": "United States"
}
],
"metricValues": [
{
"value": "638572"
}
]
},
{
"dimensionValues": [
{
"value": "Web traffic"
},
{
"value": "Japan"
}
],
"metricValues": [
{
"value": "376578"
}
]
},
{
"dimensionValues": [
{
"value": "App traffic"
},
{
"value": "United States"
}
],
"metricValues": [
{
"value": "79527"
}
]
},
...
],
...
}