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 peut être utilisée pour 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 demandes 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 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. Vous trouverez ci-dessous 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. Vous trouverez ci-dessous 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. Vous trouverez ci-dessous 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 l'ID de votre propriété.

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

Étape 2 : Trouvez la métrique "Taux d'événements clés" pour un événement clé sur lequel vous souhaitez créer des rapports à partir de la réponse. 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. Vous trouverez ci-dessous 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 moyenne de 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": "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. Vous trouverez ci-dessous 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 fidélisation des utilisateurs pour la cohorte. Pour obtenir une documentation détaillée sur chaque champ d'API, consultez la référence REST pour CohortSpec.

Créer un rapport sur les cohortes

Voici un exemple de rapport sur les cohortes :

  • La cohorte est constituée d'utilisateurs dont le 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 les cohortes affichera trois colonnes, qui sont 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 encore actifs.
  • L'objet cohortsRange spécifie que le rapport doit contenir des données d'événement commençant à 2020-12-01 et se terminant à 2020-12-06 pour cette cohorte.
    • Lorsque vous utilisez une précision de DAILY, nous vous recommandons d'utiliser la dimension cohortNthDay pour plus de cohérence.

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

Voici un exemple de réponse à 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 pour ce rapport sur les cohortes est présenté à partir de la réponse du rapport. Ce rapport révèle 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 de cohortes au fil du temps

Cohortes multiples 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 % 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 sur votre propriété sera différent pour ces trois jours, nous comparons la métrique "Fraction d'utilisateurs fidèles" de la cohorte (cohortActiveUsers/cohortTotalUsers) au lieu d'utiliser la métrique directe cohortActiveUsers.

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

Voici un exemple de réponse à 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 pour ce rapport sur les cohortes est présenté à partir de la réponse du rapport. Ce rapport révèle que la fidélisation des utilisateurs sur quatre jours a augmenté de 10 % en deux semaines. La cohorte ultérieure avec firstSessionDate de 2020-11-16 dépasse la fidélisation de la cohorte antérieure avec firstSessionDate de 2020-11-02.

Graphique de la fidélisation de plusieurs cohortes

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

Pour supprimer la variance quotidienne dans le comportement des utilisateurs, utilisez des cohortes hebdomadaires. Dans les rapports sur les cohortes hebdomadaires, tous les utilisateurs ayant effectué 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 enregistré une activité en Russie à ceux ayant enregistré 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"
    }
  },
}

Voici un exemple de réponse à 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 suit cette réponse. D'après ce rapport, cette propriété est plus efficace pour fidéliser les utilisateurs ayant une activité au Mexique que ceux ayant une activité en Russie.

Graphique des cohortes de comparaison des 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 à celle de l'interface utilisateur Google Analytics.

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

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 de l'application", utilise inListFilter pour faire correspondre la dimension platform aux 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"
        }
      ]
    },

    ...

  ],

...

}