Casi d'uso avanzati

Questo documento descrive diverse funzionalità avanzate dell'API di dati Google Analytics 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 su dimensioni personalizzate e metriche personalizzate registrate. Il metodo dell'API Metadata può essere utilizzato per elencare i nomi API delle definizioni personalizzate registrate della tua proprietà. Questi nomi API possono essere utilizzati nelle richieste di report, ad esempio per il metodo runReport.

Le sezioni seguenti mostrano esempi per ogni tipo di definizione personalizzata. In questi esempi, sostituisci GA_PROPERTY_ID con l'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 per cui vuoi 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 è riportato un esempio di richiesta 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 per cui vuoi creare report nella 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 è riportato un esempio di richiesta 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 per cui vuoi creare report nella 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 è riportato un esempio di richiesta 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 l'ID proprietà.

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

Passaggio 2: trova la metrica sul tasso di eventi chiave per un singolo evento chiave per cui vuoi creare report nella risposta. Se l'evento chiave non è presente, devi configurare l'evento chiave.

"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 è riportato un esempio di richiesta 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 dell'API Metadata con l'ID proprietà.

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

Passaggio 2: trova la media delle metriche personalizzate basate sugli eventi per cui vuoi creare report nella 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 delle metriche personalizzate in una richiesta di report. Di seguito è riportato un esempio di richiesta 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

Di seguito è riportato un esempio di report sulle coorti in cui:

  • La coorte è costituita da utenti con una firstSessionDate di 2020-12-01; questa impostazione è configurata 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; questa impostazione è configurata dagli oggetti dimensioni e metriche.
    • La dimensione cohort è il nome della coorte.
    • La dimensione cohortNthDay è il numero di giorni trascorsi dal 2020-12-01.
    • La metrica cohortActiveUsers è il numero di utenti ancora attivi.
  • L'oggetto cohortsRange specifica che il report deve contenere i dati degli eventi a partire dal 2020-12-01 e fino al 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"
    }
  },
}

Di seguito è riportato un esempio di risposta del report per questa richiesta:

{
  "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
}

Di seguito è riportato un grafico per questo report sulle coorti. Un'informazione ricavata da questo report è che il calo maggiore di 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 una firstSessionDate di 2020-11-02, la seconda con una firstSessionDate di 2020-11-09 e la terza con una firstSessionDate di 2020-11-16. Poiché il numero di utenti nella tua proprietà sarà diverso per questi tre giorni, confrontiamo la metrica della frazione di fidelizzazione degli utenti della coorte 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"
    }
  },
}

Di seguito è riportato un esempio di risposta del report per questa richiesta:

{
  "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
}

Di seguito è riportato un grafico per questo report sulle coorti. Un'informazione ricavata da 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 fidelizzazione della coorte precedente con firstSessionDate di 2020-11-02.

Grafico di più tassi di fidelizzazione delle coorti

Coorti settimanali e utilizzo delle coorti con altre funzionalità 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. Inoltre, in questo report, stiamo segmentando la coorte per confrontare gli utenti con attività in Russia con gli utenti con attività in Messico. Questa segmentazione 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"
    }
  },
}

Di seguito è riportato un esempio di risposta del report per questa richiesta:

{
  "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 per questo report sulle coorti. In base a questo report, questa proprietà è più efficace nel fidelizzare 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 comparisons campo in una definizione di report. La funzionalità Confronti dell'API di dati è simile a Confronti nel frontend di Google Analytics.

Per la documentazione dettagliata di ogni campo 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.

Di seguito è riportato un esempio di report che definisce due confronti e restituisce gli utenti attivi suddivisi per paese.

Il primo confronto denominato "Traffico app" utilizza inListFilter per abbinare la dimensione platform ai valori "iOS" e "Android". Il secondo confronto denominato "Traffico web" utilizza stringFilter per abbinare 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à di confronto, il campo comparison viene aggiunto automaticamente al report generato. Questo campo contiene il nome del confronto fornito nella richiesta.

Di seguito è riportato 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"
        }
      ]
    },

    ...

  ],

...

}