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 dell'API.

Elenca le definizioni personalizzate e crea report

L'API Data può creare report sulle dimensioni personalizzate e sulle metriche personalizzate registrate. Il metodo API Metadata può essere utilizzato per elencare i nomi delle API delle definizioni personalizzate registrate della tua proprietà. Questi nomi di 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 dell'API Metadata con il tuo ID proprietà.

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

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

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

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

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

Passaggio 2: individua 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 sul tasso di eventi chiave per un singolo evento chiave

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

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

Passaggio 2: nella risposta, individua la metrica sul tasso di eventi chiave per un evento chiave su cui ti interessa creare report. 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 basate sugli eventi

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

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

Passaggio 2: individua la media della metrica personalizzata basata sugli eventi su cui ti interessa 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 dell'API, consulta la documentazione di riferimento REST per CohortSpec.

Creare un report sulle coorti

Ecco un esempio di report sulle coorti in cui:

  • La coorte è costituita dagli utenti con un valore firstSessionDate pari a 2020-12-01, configurato dall'oggetto cohorts. 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 dimensioni e metriche.
    • La dimensione cohort è il nome della coorte.
    • La dimensione cohortNthDay indica il numero di giorni 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 è consigliata 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, 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
}

Da questa risposta del report, segue un grafico per questo report sulle coorti. Un'informazione ricavata da 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 della coorte 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 di 4 giorni del 10% nel corso di due settimane.

Per creare questo report, specifichiamo tre coorti: la prima con un valore firstSessionDate pari a 2020-11-02, la seconda con un valore firstSessionDate pari a 2020-11-09 e la terza con un valore firstSessionDate pari a 2020-11-16. Poiché il numero di utenti nella tua proprietà sarà diverso per questi tre giorni, confrontiamo la metrica frazione di fidelizzazione degli utenti della 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, 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
}

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

Grafico di più fidelizzazioni delle coorti

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

Per rimuovere la varianza giornaliera del 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. Anche in questo report, stiamo suddividendo la coorte per confrontare gli utenti con attività in Russia con gli utenti con attività in Messico. Questo taglio 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, 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
}

Da questa risposta del report, segue un grafico di questo report sulle coorti. In base a questo report, questa proprietà riesce a trattenere meglio gli utenti con attività in Messico rispetto agli utenti 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 di report. La funzionalità Confronti dell'API di dati è simile ai confronti nel frontend di Google Analytics.

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

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 trovare una corrispondenza con la dimensione platform con i valori "iOS" e "Android". Il secondo confronto denominato "Traffico web" utilizza stringFilter per associare la dimensione platform a "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à dei confronti, 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"
        }
      ]
    },

    ...

  ],

...

}