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 la documentazione di riferimento API.

Elenco delle definizioni personalizzate e creazione dei report

L'API di dati può creare report sulle dimensioni personalizzate e sulle metriche personalizzate registrate. Il Metodo API metadati può essere utilizzato per elencare i nomi API delle definizioni personalizzate registrate della tua proprietà. Ad esempio, i nomi di queste API possono essere utilizzati nelle richieste di report al metodo runReport.

Le seguenti sezioni mostrano esempi per ogni tipo di definizione personalizzata. In questi esempi, sostituisci GA4_PROPERTY_ID con il tuo ID proprietà.

Dimensioni personalizzate con ambito evento

Passaggio 1: esegui una query sul metodo dell'API metadata con il tuo ID proprietà.

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

Passaggio 2. Individua la dimensione personalizzata basata sugli eventi per la quale ti interessa creare report a partire dalla 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 per il metodo runReport.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
  "dimensions": [{ "name": "customEvent:achievement_id" }],
  "metrics": [{ "name": "eventCount" }]
}

Dimensioni personalizzate con ambito utente

Passaggio 1: esegui una query sul metodo dell'API metadata con il tuo ID proprietà.

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

Passaggio 2. Individua la dimensione personalizzata basata sull'utente per la quale vuoi creare report a partire 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 per il metodo runReport.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "entity": { "propertyId": "GA4_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 il tuo ID proprietà.

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

Passaggio 2: trova la metrica personalizzata basata sugli eventi per la quale 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 per il metodo runReport.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "customEvent:credits_spent" }]
}

Metriche del tasso di conversione per una conversione

Passaggio 1: esegui una query sul metodo dell'API metadata con il tuo ID proprietà.

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

Passaggio 2. Trova la metrica del tasso di conversione per una conversione per la quale ti interessa creare report a partire dalla risposta. Se l'evento di conversione non è presente, devi configurarlo.

"metrics": [
...
    {
      "apiName": "sessionConversionRate:add_to_cart",
      "uiName": "Session conversion rate for add_to_cart",
      "description": "The percentage of sessions in which a specific conversion event was triggered",
    },
...
],

Passaggio 3: includi la metrica del tasso di conversione in una richiesta di report. Di seguito è riportata una richiesta di esempio per il metodo runReport.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "sessionConversionRate:add_to_cart" }]
}

Medie delle metriche personalizzate con ambito evento

Passaggio 1: esegui una query sul metodo dell'API metadata con il tuo ID proprietà.

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

Passaggio 2: trova la media della metrica personalizzata basata sugli eventi per cui ti interessa creare report a partire 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 per il metodo runReport.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "2020-11-01", "endDate": "2020-11-10" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "averageCustomEvent:credits_spent" }]
}

Esempi di report di coorte

I report sulle coorti creano una serie temporale di fidelizzazione utenti per la coorte. Per una documentazione dettagliata di ciascun campo dell'API, consulta il riferimento REST per CohortSpec.

Creazione di un report sulle coorti

Ecco un esempio di report sulle coorti in cui:

• La coorte è composta da utenti con un valore firstSessionDate pari a 2020-12-01; questo valore è configurato dall'oggetto cohorts. Le dimensioni e le metriche nella risposta al report si baseranno solo sugli utenti della coorte.
• Il report sulle coorti mostrerà tre colonne configurate dagli oggetti dimensioni e metriche.
  • La dimensione cohort è il nome della coorte.
  • La dimensione cohortNthDay indica 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 che vanno dal giorno 2020-12-01 al giorno 2020-12-06 per questa coorte.
  • Quando viene utilizzata una granularità di DAILY, la dimensione cohortNthDay è consigliata per garantire la coerenza.

La richiesta di report per la coorte è:

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_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 al 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 al report, segue un grafico per questo report di coorte. Un dato di questo report indica che il calo maggiore di utenti attivi per questa coorte si verifica tra il primo e il secondo giorno.

Coorti multiple e frazione di fidelizzazione utenti

Acquisizione e fidelizzazione utenti sono modi per far crescere il tuo sito web o la tua app. I report di coorte si concentrano sulla fidelizzazione utenti. In questo esempio, il report mostra che questa proprietà ha migliorato del 10% la fidelizzazione utenti di 4 giorni nell'arco di due settimane.

Per creare questo report, specifichiamo tre coorti: la prima con firstSessionDate pari a 2020-11-02, la seconda con firstSessionDate pari a 2020-11-09 e la terza con firstSessionDate pari a 2020-11-16. Poiché il numero di utenti nella tua proprietà sarà diverso per questi tre giorni, confrontiamo la metrica della frazione di fidelizzazione utenti della coorte, pari a cohortActiveUsers/cohortTotalUsers, anziché utilizzare la metrica cohortActiveUsers diretta.

La richiesta di report per queste coorti è:

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_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 al 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 al report, segue un grafico per questo report di coorte. Un insight di questo report indica 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 varianza giornaliera nel comportamento degli utenti, utilizza le coorti settimanali. Nei report settimanali sulle coorti, tutti gli utenti con firstSessionDate nella stessa settimana formano la coorte. Le settimane iniziano la domenica e terminano il sabato. Sempre in questo report, 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 dimensionFilter per considerare solo i due paesi.

La richiesta di report per queste coorti è:

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_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 al 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, segue un grafico di questo report di coorte. In base a questo report, questa proprietà sta registrando un rendimento migliore nella fidelizzazione degli utenti con attività in Messico rispetto agli utenti con attività in Russia.