Cas d'utilisation avancés

Ce document décrit plusieurs fonctionnalités avancées de la version 1 de l'API Google Analytics Data. Pour obtenir une documentation de référence détaillée de l'API, consultez la documentation de référence de l'API.

Lister les définitions personnalisées et créer des rapports

L'API Data 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 lister les noms d'API des définitions personnalisées enregistrées de votre propriété. Ces noms d'API peuvent être utilisés dans les requêtes de rapport à la méthode runReport, par exemple.

Les sections suivantes présentent des exemples pour chaque type de définition personnalisée. Dans ces exemples, remplacez GA_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 Métadonnées avec votre ID de propriété.

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

Étape 2:Dans la réponse, recherchez la dimension personnalisée de portée événement pour laquelle vous souhaitez créer des rapports. 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/GA_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
  "dimensions": [{ "name": "customEvent:achievement_id" }],
  "metrics": [{ "name": "eventCount" }]
}

Dimensions personnalisées axées sur les utilisateurs

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

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

Étape 2:Dans la réponse, recherchez la dimension personnalisée de portée utilisateur sur laquelle vous souhaitez créer des rapports. 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/GA_PROPERTY_ID:runReport
{
  "entity": { "propertyId": "GA_PROPERTY_ID" },
  "dateRanges": [{ "startDate": "7daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "customUser:last_level" }],
  "metrics": [{ "name": "activeUsers" }]
}

Métriques personnalisées axées sur les événements

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

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

Étape 2:Dans la réponse, recherchez la métrique personnalisée de portée événement pour laquelle vous souhaitez créer des rapports. 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/GA_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "customEvent:credits_spent" }]
}

Métriques sur les taux d'événements clés pour un événement clé

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

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

Étape 2:Dans la réponse, recherchez la métrique "Taux d'événements clés" pour un événement clé pour lequel vous souhaitez créer des rapports. Si l'événement clé n'est pas présent, vous devez configurer l'événement clé.

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

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

Moyennes des métriques personnalisées de portée événement

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

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

Étape 2:Dans la réponse, recherchez la métrique personnalisée de portée événement sur laquelle vous souhaitez créer des rapports. 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/GA_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 la rétention des utilisateurs pour la cohorte. Pour obtenir une documentation détaillée de 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:

  • La cohorte correspond aux utilisateurs dont la valeur firstSessionDate est 2020-12-01. Cette valeur est configurée par l'objet cohorts. Les dimensions et les métriques de la réponse du rapport ne seront basées que sur les utilisateurs de la cohorte.
  • Le rapport sur les cohortes affiche trois colonnes, qui sont configurées par les objets de dimension et de métrique.
    • La dimension cohort correspond au nom de la cohorte.
    • La dimension cohortNthDay correspond au nombre de jours écoulés depuis 2020-12-01.
    • La métrique cohortActiveUsers correspond au nombre d'utilisateurs toujours actifs.
  • L'objet cohortsRange spécifie que le rapport doit contenir des données d'événement à partir de 2020-12-01 et se terminant par 2020-12-06 pour cette cohorte.
    • Lorsque vous utilisez une granularité de DAILY, la dimension cohortNthDay est recommandée pour plus de cohérence.

La requête de rapport pour la cohorte est la suivante:

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

Pour cette requête, voici un exemple de réponse de rapport:

{
  "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 pour ce rapport sur les cohortes s'affiche ensuite. Ce rapport indique que la plus forte baisse du nombre d'utilisateurs actifs pour cette cohorte se situe entre le premier et le deuxième jour.

Visualisation des utilisateurs de la cohorte au fil du temps

Plusieurs cohortes et fraction de fidélisation des utilisateurs

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

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

La demande de rapport pour ces cohortes est la suivante:

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

Pour cette requête, voici un exemple de réponse de rapport:

{
  "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 pour ce rapport sur les cohortes s'affiche ensuite. Ce rapport indique que la rétention des utilisateurs sur quatre jours a augmenté de 10% au cours de deux semaines. La cohorte ultérieure avec firstSessionDate de 2020-11-16 dépasse la fidélisation de la cohorte précédente avec firstSessionDate de 2020-11-02.

Graphique de la rétention de plusieurs cohortes

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

Pour supprimer la variance quotidienne du comportement des utilisateurs, utilisez des cohortes hebdomadaires. Dans les rapports sur les cohortes 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. Dans ce rapport, nous segmentons également la cohorte pour comparer les utilisateurs ayant une activité en Russie avec ceux ayant une activité au Mexique. Ce découpage 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/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"
    }
  },
}

Pour cette requête, voici un exemple de réponse de rapport:

{
  "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 du rapport sur les cohortes suit cette réponse. D'après ce rapport, cet établissement parvient mieux à fidéliser les utilisateurs ayant une activité au Mexique que ceux ayant une activité en Russie.

Graphique des cohortes de comparaison par pays

Comparaisons

Vous pouvez évaluer différents sous-ensembles de données côte à côte en effectuant des comparaisons. Vous pouvez définir des comparaisons en spécifiant le champ comparisons dans une définition de rapport. La fonctionnalité "Comparaisons" de l'API Data est semblable à la fonctionnalité Comparaisons dans l'interface Google Analytics.

Pour obtenir une documentation détaillée sur chaque champ de l'API, consultez la documentation de référence REST à des fins de comparaison.

Créer une comparaison

Vous pouvez créer une comparaison distincte pour chaque ensemble de données à comparer. Par exemple, pour comparer des données d'application à des données Web, vous pouvez créer une comparaison pour les données Android et iOS, et une autre pour les données Web.

Voici un exemple de rapport qui définit deux comparaisons et renvoie les utilisateurs actifs ventilés par pays.

La première comparaison nommée "Trafic des applications" utilise inListFilter pour faire correspondre la dimension platform avec les valeurs "iOS" et "Android". La deuxième comparaison, intitulée "Trafic Web", utilise stringFilter pour faire correspondre la dimension platform à "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"
      }
    ]
  }

Pour toutes les requêtes utilisant la fonctionnalité de comparaison, le champ comparison est automatiquement ajouté au rapport généré. Ce champ contient le nom de la comparaison fournie dans la requête.

Voici un exemple d'extrait de réponse contenant des comparaisons:

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

    ...

  ],

...

}