Cas d'utilisation avancés

Ce document décrit plusieurs fonctionnalités avancées de l'API Google Analytics Data v1. Pour obtenir une documentation de référence détaillée sur 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 de l'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 envoyées à 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 l'ID de votre 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/GA_PROPERTY_ID/metadata

Étape 2 : Dans la réponse, recherchez la dimension personnalisée de portée événement sur 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 Metadata 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 Metadata 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": "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 Metadata 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é sur lequel vous souhaitez créer des rapports. Si l'événement clé n'est pas présent, vous devez le configurer.

"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 Metadata 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 Average 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 une cohorte

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 sur chaque champ de l'API, consultez la documentation de référence REST pour CohortSpec.

Créer un rapport sur une cohorte

Voici un exemple de rapport sur une cohorte :

  • La cohorte est composée d'utilisateurs dont la valeur firstSessionDate est 2020-12-01. Elle 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 une cohorte 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 spécifie que le rapport doit contenir les données d'événement de cette cohorte entre le 2020-12-01 et le 2020-12-06.
    • Lorsqu'une précision de DAILY est utilisée, la dimension cohortNthDay est recommandée pour des raisons 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
}

La réponse à ce rapport est suivie d'un graphique pour ce rapport sur une cohorte. Ce rapport indique que la plus forte baisse du nombre d'utilisateurs actifs pour cette cohorte se produit entre le premier et le deuxième jour.

Visualisation des utilisateurs d'une cohorte au fil du temps

Plusieurs cohortes et fraction de rétention des utilisateurs

L'acquisition d'utilisateurs et la rétention des utilisateurs sont des moyens de développer votre site Web ou votre application. Les rapports sur les cohortes se concentrent sur la rétention des utilisateurs. Dans cet exemple, le rapport montre que cette propriété a amélioré de 10 % la rétention des utilisateurs sur quatre jours en 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 de votre propriété sera différent pour ces trois jours, nous comparons la métrique de fraction de rétention des utilisateurs de la cohorte de cohortActiveUsers/cohortTotalUsers plutôt que d'utiliser la métrique directe cohortActiveUsers.

La requête 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
}

Voici un graphique pour ce rapport sur une cohorte, basé sur la réponse de ce rapport. Ce rapport indique que la rétention des utilisateurs sur quatre jours a augmenté de 10 % en deux semaines. La cohorte ultérieure avec un firstSessionDate de 2020-11-16 dépasse la rétention de la cohorte antérieure avec un firstSessionDate de 2020-11-02.

Graphique de rétention de plusieurs cohortes

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

Pour éliminer les variations quotidiennes du comportement des utilisateurs, utilisez des cohortes hebdomadaires. Dans les rapports sur les cohortes hebdomadaires, tous les utilisateurs ayant 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. Cette segmentation utilise la dimension country et un dimensionFilter pour ne prendre en compte que les deux pays.

La requête 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
}

Cette réponse au rapport est suivie d'un graphique du rapport sur les cohortes. 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é de comparaison de l'API Data est semblable aux comparaisons dans l'interface de Google Analytics.

Pour obtenir une documentation détaillée sur chaque champ de l'API, consultez la documentation de référence REST pour Comparison.

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 répartis par pays.

La première comparaison, nommée "Trafic de l'application", utilise l'inListFilter pour faire correspondre la dimension platform aux valeurs "iOS" et "Android". La deuxième comparaison, nommée "Trafic Web", utilise l'opérateur 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"
        }
      ]
    },

    ...

  ],

...

}