API User Activity

L'API User Activity permet à un propriétaire de propriété Google Analytics de récupérer toutes les données de mesure analytiques associées à un seul utilisateur. Plus précisément, l'API récupère toutes les données de mesure associées à un User-ID ou un Client-ID spécifique.

Envoyer une requête d'activité de l'utilisateur

Pour envoyer une requête d'activité de l'utilisateur, créez un objet de requête avec les champs suivants:

  1. Client-ID ou User-ID associé à l'utilisateur

  2. Un ID de vue Analytics contenant les données associées à l'utilisateur.

  3. Bien que cela ne soit pas obligatoire, vous aurez probablement besoin d'une plage de dates pour les données qui vous intéressent. Par défaut, l'API répertorie l'activité des utilisateurs au cours de la semaine passée.

Exemple de requête

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

Exemple de réponse

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

Sessions et activités

Les données sur l'activité de l'utilisateur sont regroupées par session. Chaque session contient des informations générales sur la session, telles que son ID et sa date, ainsi qu'une liste des activités de l'utilisateur. Dans une session, les activités de l'utilisateur correspondent à tous les "appels" dont l'utilisateur est responsable. Cela inclut les pages vues, les événements d'e-commerce et les événements personnalisés envoyés via gtag(...) ou ga(...).

Pagination

L'API User Activity utilise la pagination pour diviser de grands ensembles de données en plusieurs requêtes et réponses. Toutefois, comme les données renvoyées par l'API sont structurées de manière hiérarchique, le développeur doit prendre en compte certaines considérations particulières afin de classer correctement les données.

Le type de "ligne" de base utilisé pour la pagination est "Activity". Étant donné que les données utilisateur sont regroupées par session, une limite de page peut apparaître au sein d'une session, et cette session peut comporter des activités couvrant plusieurs pages.

Exemples de données

À titre de démonstration, nous utiliserons les exemples de données suivants. Dans cet exemple, l'utilisateur a interagi avec le site lors de six sessions sur une période de trois jours.

Date ID de session Libellé d'événement Temps
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

Une seule page

Si vous effectuez une requête d'activité de l'utilisateur avec un pageSize d'au moins 18, les données sont toutes transmises sur une seule page et se présentent comme suit:

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

Plusieurs pages

Toutefois, si la taille de votre page est de 5, ces données seront divisées en quatre pages de réponse:

DateID de sessionLibellé d'événementTemps
Page 1:
2018-11-231A10:26
2018-11-231B10:32
2018-11-231C10:39
2018-11-232A18:04
2018-11-232B18:11
Page 2:
2018-11-232C18:26
2018-11-243A11:26
2018-11-243B11:29
2018-11-243C11:39
2018-11-243D11:42
Page 3:
2018-11-244A23:50
2018-11-244B23:54
2018-11-255C00:02
2018-11-255D00:13
2018-11-256A13:01
Page 4:
2018-11-256B13:09
2018-11-256C13:12
2018-11-256D13:23

Notez que la session 2 est divisée entre la première et la deuxième pages, et que les deux sessions du 24 novembre sont réparties sur la deuxième et la troisième pages. Les réponses se présenteront comme suit:

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

Échantillonnage de données

Si un client a accumulé une quantité énorme de données pour la période demandée, l'API peut ne renvoyer qu'un sous-ensemble échantillonné d'activités. Dans ce cas, le champ sampleRate indique la fraction des activités de l'utilisateur qui a été renvoyée.

Mode d'échantillonnage des données

Les données utilisateur sont échantillonnées au niveau de l'activité. Par exemple, avec un taux d'échantillonnage de 50% (0.5), la moitié des activités de l'utilisateur sera présente dans la réponse.

Ces activités échantillonnées sont sélectionnées de manière arbitraire. L'API ne fournit aucune garantie concernant l'échantillonnage aléatoire, ni que l'échantillonnage est proportionnel à l'ensemble des activités pour la période donnée.

Empêcher l'échantillonnage de données

Étant donné que cette API traite une session comme un simple ensemble d'activités, les sessions pour lesquelles aucune activité n'apparaît dans l'ensemble échantillonné n'apparaîtront pas dans la réponse. Si vous avez besoin d'une liste complète des sessions ou des activités, envoyez des demandes de suivi portant sur des périodes plus courtes.

Par exemple, si vous demandez des données de 2018-01-01 à 2018-12-31 et que la réponse indique un taux d'échantillonnage de 0.25, divisez la plage de dates demandée en quatre parties, de sorte que chaque partie contienne environ un quart des données d'origine:

  • 2018-01-01 > 2018-03-31
  • De 2018-04-01 à 2018-06-30
  • De 2018-07-01 à 2018-09-30
  • 2018-10-01 > 2018-12-31