Prova il server MCP per Google Analytics. Installa da GitHub e consulta l'annuncio per maggiori dettagli.

Casi d'uso avanzati

Questo documento descrive diverse funzionalità avanzate dell'API di dati di Google Analytics v1. Per un riferimento dettagliato dell'API, consulta il Riferimento API.

Elenca le definizioni personalizzate e crea report

L'API Data può creare report su dimensioni personalizzate e metriche personalizzate registrate. Il metodo dell'API Metadata può essere utilizzato per elencare i nomi delle API delle definizioni personalizzate registrate della tua proprietà. Questi nomi API possono essere utilizzati nelle richieste di report al metodo runReport, ad esempio.

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 dell'API Metadata con l'ID proprietà.

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata

Passaggio 2: trova la dimensione personalizzata basata sugli eventi su cui ti interessa creare report nella risposta. 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 dell'API Metadata con l'ID proprietà.

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata

Passaggio 2: trova la dimensione personalizzata basata sugli utenti su cui ti interessa creare report dalla risposta. 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 dell'API Metadata con l'ID proprietà.

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata

Passaggio 2: trova la metrica personalizzata basata sugli eventi su cui ti interessa creare report dalla risposta. 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 su cui ti interessa creare 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 del 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 basate sugli eventi

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 media della metrica personalizzata basata sugli eventi su cui vuoi creare report dalla risposta. 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 della fidelizzazione degli utenti per la coorte. Per la documentazione dettagliata di ogni campo API, consulta il riferimento REST per CohortSpec.

Creare un report sulle coorti

Ecco un report coorte di esempio in cui:

La coorte è costituita da utenti con un firstSessionDate di 2020-12-01; questo valore viene configurato dall'oggetto cohorts. Le dimensioni e le metriche nella risposta del report si baseranno solo sugli utenti della coorte.
Il report sulla coorte mostrerà tre colonne, configurate dagli oggetti dimensioni e metriche.
- La dimensione cohort è il nome della coorte.
- La dimensione cohortNthDay è il numero di giorni a partire dal giorno 2020-12-01.
- La metrica cohortActiveUsers indica il numero di utenti ancora attivi.
L'oggetto cohortsRange specifica che il report deve contenere i dati sugli eventi a partire dal giorno 2020-12-01 e fino al giorno 2020-12-06 per questa coorte.
- Quando viene utilizzata una granularità di DAILY, per coerenza è consigliabile utilizzare la dimensione cohortNthDay.

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, una risposta di esempio 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
}

Da questa risposta del report segue un grafico per questo report sulle coorti. Un approfondimento di questo report è che il calo più significativo degli utenti attivi per questa coorte si verifica tra il primo e il secondo giorno.

Visualizzazione degli utenti delle coorti nel tempo

Più coorti e frazione di fidelizzazione degli 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 degli utenti in 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 nella tua proprietà sarà diverso in questi tre giorni, confrontiamo la metrica Frazione di utenti che rimangono nella coorte di cohortActiveUsers/cohortTotalUsers anziché utilizzare la metrica cohortActiveUsers diretta.

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, una risposta di esempio 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
}

Da questa risposta del report segue un grafico per questo report sulle coorti. Un approfondimento di questo report è che la fidelizzazione degli utenti di 4 giorni è aumentata del 10% nel corso di due settimane. La coorte successiva con firstSessionDate di 2020-11-16 supera la conservazione della coorte precedente con firstSessionDate di 2020-11-02.

Grafico con la fidelizzazione di più coorti

Coorti settimanali e utilizzo delle coorti con altre funzionalità dell'API

Per rimuovere la varianza 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. In questo report, inoltre, stiamo suddividendo 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 prendere in considerazione 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, una risposta di esempio 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
}

A partire da questa risposta del report, segue un grafico del report sulle coorti. In base a questo report, questa proprietà riesce a fidelizzare meglio gli utenti con attività in Messico rispetto a quelli con attività in Russia.

Grafico delle coorti di confronto tra paesi

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à Confronti dell'API di dati è simile a Confronti nel frontend di Google Analytics.

Per la documentazione dettagliata di ogni campo dell'API, consulta il riferimento REST per Comparison.

Creare 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 corrispondere alla dimensione platform con i 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 un esempio di snippet 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"
        }
      ]
    },

    ...

  ],

...

}

Casi d'uso avanzati Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Elenca le definizioni personalizzate e crea report

Dimensioni personalizzate basate sugli eventi

Dimensioni personalizzate basate sugli utenti

Metriche personalizzate con ambito evento

Metriche del tasso di eventi chiave per un singolo evento chiave

Medie delle metriche personalizzate basate sugli eventi

Esempi di report sulle coorti

Creare un report sulle coorti

Più coorti e frazione di fidelizzazione degli utenti

Coorti settimanali e utilizzo delle coorti con altre funzionalità dell'API

Confronti

Creare un confronto

Casi d'uso avanzati