API User Activity

L'API User Activity consente al proprietario di una proprietà Google Analytics di recuperare tutti i dati di misurazione di Analytics associati a un singolo utente. In particolare, l'API recupera tutti i dati di misurazione associati a uno User-ID o a un Client ID specifico.

Nota: consulta la sezione Riferimento User-ID per una breve introduzione ai Client-ID e agli User-ID e alle loro differenze.

Presentazione di una richiesta di attività utente

Per effettuare una richiesta di attività utente, crea un oggetto richiesta con i seguenti campi:

1. Il Client-ID o lo User-ID associato all'utente

   • Per ulteriori dettagli su come cercare questi campi, consulta Cookie e identificazione degli utenti.

2. Un ID vista Analytics contenente i dati associati all'utente.

   • Puoi utilizzare Esplora account per cercare l'ID vista.

3. Sebbene non sia obbligatorio, probabilmente avrai bisogno di un intervallo di date per i dati che ti interessano. Per impostazione predefinita, l'API elenca le attività degli utenti nell'ultima settimana.

Nota: consulta la documentazione di riferimento per un elenco completo dei campi accettati da questa API, inclusi i valori predefiniti per i campi facoltativi.

Esempio di richiesta

POST https://analyticsreporting.googleapis.com/v4/userActivity:search

{
    "viewId": "9999999",
    "user": {
        "type": "CLIENT_ID",
        "userId": "1034600000.76425000000"
    },
    "dateRange": {
        "startDate": "2018-01-01",
        "endDate": "2018-12-31",
    }
}

Esempio di risposta

{
    "sessions": [{
        "sessionId": "1539184430",
        "deviceCategory": "desktop",
        "platform": "Windows",
        "dataSource": "web",
        "sessionDate": "2018-10-10"
        "activities": [{
            "activityTime": "2018-10-10T08:13:50.555105Z",
            "source": "(direct)",
            "medium": "(none)",
            "channelGrouping": "Direct",
            "campaign": "(not set)",
            "keyword": "(not set)",
            "hostname": "shop.googlemerchandisestore.com",
            "landingPagePath": "/gpsmap",
            "activityType": "PAGEVIEW",
            "customDimension": [{
                "index": 1,
                "value": "(not set)"
            }, ...]
        }, ...]
    }, ...]
    "totalRows": 1000,
    "nextPageToken": "A6JGY3",
    "sampleRate": 1
}

Nota: in questo esempio, utilizziamo ... per indicare gli array troncati

Sessioni e attività

I dati sull'attività utente vengono raggruppati per sessione. Ogni sessione contiene informazioni generali sulla sessione, ad esempio l'ID e la data della sessione, nonché un elenco di attività utente per la sessione. Le attività utente in una sessione consistono in ogni "hit" per cui l'utente era responsabile; sono inclusi, ad esempio, visualizzazioni di pagina, eventi di e-commerce ed eventi personalizzati inviati tramite gtag(...) o ga(...).

Nota: le sessioni non possono superare i limiti di date. Se il tempo trascorso da un utente sul tuo sito include due giorni diversi, verranno visualizzati due sessioni diverse, in date diverse. Per ulteriori informazioni su come viene definita una sessione in Google Analytics, consulta Come viene definita una sessione web in Analytics

Nota: il riferimentoActivity contiene una definizione più precisa di un'attività e i modi discreti in cui è distinta da un hit o da un evento.

Impaginazione

L'API User Activity utilizza l'impaginazione per suddividere set di dati di grandi dimensioni in più richieste e risposte. Tuttavia, poiché i dati restituiti dall'API sono strutturati in modo gerarchico, lo sviluppatore deve fare alcune considerazioni particolari per raccogliere correttamente i dati.

Il tipo di "riga" di base ai fini dell'impaginazione è l'Attività. Poiché i dati utente sono raggruppati per sessione, significa che un confine di pagina può verificarsi all'interno di una sessione, che può includere attività su più pagine.

Punto chiave: i limiti della pagina possono verificarsi all'interno di una sessione.

Dati di esempio

A scopo dimostrativo, utilizzeremo i seguenti dati di esempio. In questo esempio, l'utente ha interagito con il sito in 6 sessioni nell'arco di 3 giorni.

Data	ID sessione	Etichetta evento	Tempo
2018-11-23	1	A	10:26
2018-11-23	1	B	10:32
2018-11-23	1	C	10:39
2018-11-23	2	A	18:04
2018-11-23	2	B	18:11
2018-11-23	2	C	18:26
2018-11-24	3	A	11:26
2018-11-24	3	B	11:29
2018-11-24	3	C	11:39
2018-11-24	3	D	11:42
2018-11-24	4	A	23:50
2018-11-24	4	B	23:54
2018-11-25	5	C	00:02
2018-11-25	5	D	00:13
2018-11-25	6	A	13:01
2018-11-25	6	B	13:09
2018-11-25	6	C	13:12
2018-11-25	6	D	13:23

Pagina singola

Se invii una richiesta di attività utente con un valore pageSize pari ad almeno 18, i dati verranno tutti inviati in un'unica pagina e avranno un aspetto simile al seguente:

POST https://analyticsreporting.googleapis.com/v4/userActivity:search

{
    "viewId": "9999999",
    "user": {
        "type": "CLIENT_ID",
        "userId": "1034600000.76425000000",
    },
    "dateRange": {
        "startDate": "2018-11-20",
        "endDate": "2018-11-30",
    },
    "pageSize": 100,
}

{
    "totalRows": 18,
    "sessions": [{
            "sessionId": "1",
            "sessionDate": "2018-11-23",
            "activities": [{
                    "activityTime": "2018-11-23T10:26:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-23T10:32:00",
                    "event": {"eventLabel": "B"}
                }, {
                    "activityTime": "2018-11-23T10:39:00",
                    "event": {"eventLabel": "C"}
                }]
        }, {
            "sessionId": "2",
            "sessionDate": "2018-11-23",
            "activities": [{
                    "activityTime": "2018-11-23T18:04:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-23T18:11:00",
                    "event": {"eventLabel": "B"}
                }, {
                    "activityTime": "2018-11-23T18:26:00",
                    "event": {"eventLabel": "C"}
                }]
        }, {
            "sessionId": "3",
            "sessionDate": "2018-11-24",
            "activities": [{
                    "activityTime": "2018-11-24T11:26:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-24T11:29:00",
                    "event": {"eventLabel": "B"}
                }, {
                    "activityTime": "2018-11-24T11:39:00",
                    "event": {"eventLabel": "C"}
                }, {
                    "activityTime": "2018-11-24T11:42:00",
                    "event": {"eventLabel": "D"}
                }]
        }, {
            "sessionId": "4",
            "sessionDate": "2018-11-24",
            "activities": [{
                    "activityTime": "2018-11-24T23:50:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-24T23:54:00",
                    "event": {"eventLabel": "B"}
                }]
        }, {
            "sessionId": "5",
            "sessionDate": "2018-11-25",
            "activities": [{
                    "activityTime": "2018-11-25T00:01:00",
                    "event": {"eventLabel": "C"}
                }, {
                    "activityTime": "2018-11-25T00:13:00",
                    "event": {"eventLabel": "D"}
                }]
        }, {
            "sessionId": "6",
            "sessionDate": "2018-11-25",
            "activities": [{
                    "activityTime": "2018-11-25T13:01:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-25T13:09:00",
                    "event": {"eventLabel": "B"}
                }, {
                    "activityTime": "2018-11-25T10:12:00",
                    "event": {"eventLabel": "C"}
                }, {
                    "activityTime": "2018-11-25T10:23:00",
                    "event": {"eventLabel": "D"}
                }]
        }]
}

Nota: molti campi sono stati omessi per brevità; questo esempio ha il solo scopo di mostrare il raggruppamento gerarchico di attività e sessioni.

Più pagine

Tuttavia, se la dimensione della pagina è 5, questi dati verranno suddivisi in quattro pagine di risposta:

Data	ID sessione	Etichetta evento	Tempo
Pagina 1:
2018-11-23	1	A	10:26
2018-11-23	1	B	10:32
2018-11-23	1	C	10:39
2018-11-23	2	A	18:04
2018-11-23	2	B	18:11
Pagina 2:
2018-11-23	2	C	18:26
2018-11-24	3	A	11:26
2018-11-24	3	B	11:29
2018-11-24	3	C	11:39
2018-11-24	3	D	11:42
Pagina 3:
2018-11-24	4	A	23:50
2018-11-24	4	B	23:54
2018-11-25	5	C	00:02
2018-11-25	5	D	00:13
2018-11-25	6	A	13:01
Pagina 4:
2018-11-25	6	B	13:09
2018-11-25	6	C	13:12
2018-11-25	6	D	13:23

Nota: le attività utente sono sempre in ordine ordinato, il che significa che il confine tra le pagine non sarà mai casuale; sarà sempre tra sessioni e attività adiacenti al tempo.

Nota che la sessione 2 è suddivisa tra la prima e la seconda pagina, mentre le due sessioni del 24 novembre sono suddivise nella seconda e terza pagina. Le risposte saranno simili a queste:

{
    "totalRows": 18,
    "nextPageToken": "UGMGQS",
    "sessions": [{
            "sessionId": "1",
            "sessionDate": "2018-11-23",
            "activities": [{
                    "activityTime": "2018-11-23T10:26:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-23T10:32:00",
                    "event": {"eventLabel": "B"}
                }, {
                    "activityTime": "2018-11-23T10:39:00",
                    "event": {"eventLabel": "C"}
                }]
        }, {
            "sessionId": "2",
            "sessionDate": "2018-11-23",
            "activities": [{
                    "activityTime": "2018-11-23T18:04:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-23T18:11:00",
                    "event": {"eventLabel": "B"}
                }]
        }]
}

{
    "totalRows": 18,
    "nextPageToken": "1FKOME",
    "sessions": [{
            "sessionId": "2",
            "sessionDate": "2018-11-23",
            "activities": [{
                    "activityTime": "2018-11-23T18:26:00",
                    "event": {"eventLabel": "C"}
                }]
        }, {
            "sessionId": "3",
            "sessionDate": "2018-11-24",
            "activities": [{
                    "activityTime": "2018-11-24T11:26:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-24T11:29:00",
                    "event": {"eventLabel": "B"}
                }, {
                    "activityTime": "2018-11-24T11:39:00",
                    "event": {"eventLabel": "C"}
                }, {
                    "activityTime": "2018-11-24T11:42:00",
                    "event": {"eventLabel": "D"}
                }]
        }]
}

{
    "totalRows": 18,
    "nextPageToken": "7S77H6",
    "sessions": [{
            "sessionId": "4",
            "sessionDate": "2018-11-24",
            "activities": [{
                    "activityTime": "2018-11-24T23:50:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-24T23:54:00",
                    "event": {"eventLabel": "B"}
                }]
        }, {
            "sessionId": "5",
            "sessionDate": "2018-11-25",
            "activities": [{
                    "activityTime": "2018-11-25T00:01:00",
                    "event": {"eventLabel": "C"}
                }, {
                    "activityTime": "2018-11-25T00:13:00",
                    "event": {"eventLabel": "D"}
                }]
        }, {
            "sessionId": "6",
            "sessionDate": "2018-11-25",
            "activities": [{
                    "activityTime": "2018-11-25T13:01:00",
                    "event": {"eventLabel": "A"}
                }]
        }]
}

{
    "totalRows": 18,
    "sessions": [{
            "sessionId": "6",
            "sessionDate": "2018-11-25",
            "activities": [{
                    "activityTime": "2018-11-25T13:09:00",
                    "event": {"eventLabel": "B"}
                }, {
                    "activityTime": "2018-11-25T10:12:00",
                    "event": {"eventLabel": "C"}
                }, {
                    "activityTime": "2018-11-25T10:23:00",
                    "event": {"eventLabel": "D"}
                }]
        }]
}

Campionamento dei dati

Se un client ha accumulato un'enorme quantità di dati per l'intervallo di date richiesto, l'API potrebbe restituire solo un sottoinsieme campionato di attività. Quando ciò si verifica, il campo sampleRate indicherà quale frazione delle attività dell'utente è stata restituita.

Come vengono campionati i dati

I dati utente vengono campionati a livello di attività. Ad esempio, con una frequenza di campionamento del 50% (0.5), metà delle attività dell'utente sarà presente nella risposta.

Queste attività campionate vengono selezionate in modo arbitrario; l'API non fornisce alcuna garanzia sul campionamento casuale, né il campionamento è proporzionale tra le attività per l'intervallo di date specificato.

Evitare il campionamento dei dati

Poiché questa API tratta una sessione come una semplice raccolta di attività, tutte le sessioni per le quali non sono presenti attività nell'insieme campionato non verranno visualizzate nella risposta. Se hai bisogno di un elenco completo di sessioni o attività, effettua richieste di follow-up con intervalli di date più brevi.

Ad esempio, se richiedi dati da 2018-01-01 a 2018-12-31 e la risposta indica una frequenza di campionamento pari a 0.25, dividi l'intervallo di date richiesto in quattro parti, in modo che ogni parte contenga circa un quarto dei dati originali:

• Da 2018-01-01 a 2018-03-31
• Da 2018-04-01 a 2018-06-30
• Da 2018-07-01 a 2018-09-30
• Da 2018-10-01 a 2018-12-31

Nota: a causa di un possibile clustering di dati casuali, anche questi sottointervalli potrebbero essere campionati. Ad esempio, se la maggior parte dei dati dell'utente si è verificata nell'intervallo di date 2018-01-01 - 2018-03-31, potresti dover eseguire richieste aggiuntive fino a ottenere tutti i dati non campionati.