Cas d'utilisation avancés

Ce document décrit plusieurs fonctionnalités avancées de l'API Data de Google Analytics v1. Pour plus d'informations sur l'API, consultez la documentation de référence sur l'API.

Répertorier les définitions personnalisées et créer des rapports

Data API peut créer des rapports sur les dimensions personnalisées et les métriques personnalisées enregistrées. La méthode API Metadata permet de répertorier les noms d'API des définitions personnalisées enregistrées de votre propriété. Ces noms d'API peuvent par exemple être utilisés dans les requêtes de rapport envoyées à la méthode runReport.

Les sections suivantes présentent des exemples pour chaque type de définition personnalisée. Dans ces exemples, remplacez GA4_PROPERTY_ID par votre ID de propriété.

Dimensions personnalisées de portée événement

Étape 1:Interrogez la méthode de l'API Metadata avec votre ID de propriété.

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

Étape 2:Recherchez la dimension personnalisée de portée événement pour laquelle vous souhaitez créer des rapports à partir de la réponse. Si la dimension n'est pas présente, vous devez l'enregistrer.

"dimensions": [
...
    {
      "apiName": "customEvent:achievement_id",
      "uiName": "Achievement ID",
      "description": "An event scoped custom dimension for your Analytics property."
    },
...
],

Étape 3:Incluez la dimension personnalisée dans une demande de rapport. Voici un exemple de requête envoyée à la méthode 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" }]
}

Dimensions personnalisées de portée utilisateur

Étape 1:Interrogez la méthode de l'API Metadata avec votre ID de propriété.

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

Étape 2:Recherchez la dimension personnalisée de portée utilisateur pour laquelle vous souhaitez créer des rapports à partir de la réponse. Si la dimension n'est pas présente, vous devez l'enregistrer.

"dimensions": [
...
    {
      "apiName": "customUser:last_level",
      "uiName": "Last level",
      "description": "A user property for your Analytics property."
    },
...
],

Étape 3:Incluez la dimension personnalisée dans une demande de rapport. Voici un exemple de requête envoyée à la méthode 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" }]
}

Métriques personnalisées de portée événement

Étape 1:Interrogez la méthode de l'API Metadata avec votre ID de propriété.

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

Étape 2:Recherchez la métrique personnalisée de portée événement pour laquelle vous souhaitez créer des rapports à partir de la réponse. Si la métrique n'est pas présente, vous devez l'enregistrer.

"metrics": [
...
    {
      "apiName": "customEvent:credits_spent",
      "uiName": "Credits Spent",
      "description": "An event scoped custom metric for your Analytics property.",
      "type": "TYPE_STANDARD"
    },
...
],

Étape 3:Incluez la métrique personnalisée dans une demande de rapport. Voici un exemple de requête envoyée à la méthode 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" }]
}

Métriques de taux de conversion pour une conversion

Étape 1:Interrogez la méthode de l'API Metadata avec votre ID de propriété.

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

Étape 2:Recherchez la métrique du taux de conversion d'une conversion sur laquelle vous souhaitez créer des rapports à partir de la réponse. Si l'événement de conversion n'est pas présent, vous devez le configurer.

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

Étape 3:Incluez la métrique du taux de conversion dans une demande de rapport. Voici un exemple de requête envoyée à la méthode 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" }]
}

Moyennes des métriques personnalisées basées sur les événements

Étape 1:Interrogez la méthode de l'API Metadata avec votre ID de propriété.

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

Étape 2:Trouvez la moyenne de la métrique personnalisée de portée événement qui vous intéresse pour créer des rapports à partir de la réponse. Si la métrique n'est pas présente, vous devez l'enregistrer.

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

Étape 3:Incluez la moyenne de la métrique personnalisée dans une demande de rapport. Voici un exemple de requête envoyée à la méthode 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" }]
}

Exemples de rapports sur les cohortes

Les rapports sur les cohortes créent une série temporelle de fidélisation des utilisateurs pour la cohorte. Pour obtenir une documentation détaillée sur chaque champ de l'API, consultez la documentation de référence REST pour CohortSpec.

Créer un rapport sur les cohortes

Voici un exemple de rapport sur les cohortes dans lequel:

  • La cohorte est constituée d'utilisateurs dont le firstSessionDate est 2020-12-01. Ce paramètre est configuré par l'objet cohorts. Les dimensions et métriques contenues dans la réponse du rapport seront basées uniquement sur les utilisateurs de la cohorte.
  • Le rapport sur les cohortes comporte trois colonnes, configurées par les objets de dimensions et de métriques.
    • La dimension cohort correspond au nom de la cohorte.
    • La dimension cohortNthDay correspond au nombre de jours écoulés depuis le 2020-12-01.
    • La métrique cohortActiveUsers correspond au nombre d'utilisateurs toujours actifs.
  • L'objet cohortsRange indique que le rapport doit contenir des données d'événement commençant le 2020-12-01 et se terminant à 2020-12-06 pour cette cohorte.
    • Lorsqu'une précision de DAILY est utilisée, la dimension cohortNthDay est recommandée par souci de cohérence.

La demande de rapport pour la cohorte est:

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

Voici un exemple de réponse de rapport pour cette requête:

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

Un graphique de ce rapport de cohorte apparaît à la suite de cette réponse de rapport. Ce rapport indique que la plus forte baisse du nombre d'utilisateurs actifs pour cette cohorte s'est produite entre le premier et le deuxième jour.

Visualisation des utilisateurs de la cohorte au fil du temps

Cohortes multiples et fraction de la fidélisation des utilisateurs

L'acquisition et la fidélisation des utilisateurs sont des moyens d'améliorer votre site Web ou votre application. Les rapports sur les cohortes sont axés sur la fidélisation des utilisateurs. Dans cet exemple, le rapport montre que cette propriété a amélioré la fidélisation des utilisateurs sur quatre jours de 10% en deux semaines.

Pour créer ce rapport, nous spécifions trois cohortes: la première avec la valeur de firstSessionDate pour 2020-11-02, la deuxième avec la valeur de firstSessionDate pour 2020-11-09 et la troisième avec la valeur de firstSessionDate pour 2020-11-16. Étant donné que le nombre d'utilisateurs sur votre propriété sera différent pendant ces trois jours, nous comparons la métrique de fraction de fidélisation des utilisateurs de la cohorte (cohortActiveUsers/cohortTotalUsers) plutôt que la métrique directe cohortActiveUsers.

La demande de rapport pour ces cohortes est la suivante:

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

Voici un exemple de réponse de rapport pour cette requête:

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

Un graphique de ce rapport de cohorte apparaît à la suite de cette réponse de rapport. Ce rapport indique que la fidélisation des utilisateurs sur quatre jours a augmenté de 10% en deux semaines. La cohorte la plus récente, avec la valeur firstSessionDate de 2020-11-16, dépasse la durée de conservation de la cohorte précédente avec la valeur firstSessionDate de 2020-11-02.

Graphique de fidélisation de plusieurs cohortes

Cohortes hebdomadaires et utilisation de cohortes avec d'autres fonctionnalités d'API

Utilisez des cohortes hebdomadaires pour supprimer les variations de comportement des utilisateurs au jour le jour. Dans les rapports de cohorte hebdomadaires, tous les utilisateurs avec firstSessionDate au cours de la même semaine forment la cohorte. Les semaines commencent le dimanche et se terminent le samedi. De plus, dans ce rapport, nous segmentons la cohorte pour comparer les utilisateurs actifs en Russie à ceux qui sont actifs au Mexique. Ce segment utilise la dimension country et un dimensionFilter pour ne prendre en compte que les deux pays.

La demande de rapport pour ces cohortes est la suivante:

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

Voici un exemple de réponse de rapport pour cette requête:

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

Un graphique de ce rapport sur les cohortes s'affiche à partir de la réponse à ce rapport. D'après ce rapport, cette propriété est plus efficace pour retenir les utilisateurs actifs au Mexique que ceux exerçant une activité en Russie.

Graphique des cohortes comparatives par pays