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 API Metadata Method 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 requêtes de rapport, par exemple pour la méthode runReport.

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 l'ID de votre 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 requête de rapport. Voici un exemple de requête pour 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 de portée utilisateur

É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 : Dans la réponse, recherchez la dimension personnalisée axée sur les utilisateurs pour 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 requête de rapport. Voici un exemple de requête pour 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 l'ID de votre 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 axée sur les événements 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 requête de rapport. Voici un exemple de requête pour 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 de taux d'événements clés pour un événement clé

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

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

Étape 2 : Dans la réponse, recherchez la métrique de taux d'événements clés pour un événement clé pour laquelle 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 de taux d'événements clés dans une requête de rapport. Voici un exemple de requête pour 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 axées sur les événements

É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 : Dans la réponse, recherchez la moyenne de la métrique personnalisée axée sur les événements 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 requête de rapport. Voici un exemple de requête pour 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 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 une cohorte :

  • La cohorte est constitué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 affichera trois colonnes. Il est configuré par les objets dimensions et métriques.
    • La dimension cohort correspond au nom de la cohorte.
    • La dimension cohortNthDay correspond au nombre de jours 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 le 2020-12-01 et se terminant le 2020-12-06 pour cette cohorte.
    • Lorsqu'une granularité DAILY est utilisée, la dimension cohortNthDay est recommandée pour assurer la 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"
    }
  },
}

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
}

Le graphique suivant est issu de cette réponse de 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 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 rétention des utilisateurs sur quatre jours de 10% en deux semaines.

Pour créer ce rapport, nous spécifions trois cohortes : la première avec une valeur firstSessionDate de 2020-11-02, la deuxième avec une valeur firstSessionDate de 2020-11-09 et la troisième avec une valeur 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 cohortActiveUsers/cohortTotalUsers plutôt que d'utiliser la métrique cohortActiveUsers directe.

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

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
}

Le graphique suivant est issu de cette réponse de rapport sur une cohorte. Ce rapport indique que la fidélisation des utilisateurs sur quatre jours a augmenté de 10% en deux semaines. La cohorte ultérieure avec une valeur firstSessionDate de 2020-11-16 dépasse la fidélisation de la cohorte antérieure avec une valeur firstSessionDate de 2020-11-02.

Graphique de la fidélisation 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 dont la valeur firstSessionDate se situe dans 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 à 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"
    }
  },
}

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
}

Le graphique suivant est issu de cette réponse de rapport sur une cohorte. 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 comparisons champ dans une définition de rapport. La fonctionnalité de comparaison de l'API Data est semblable à celle de l'interface utilisateur 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 ventilés par pays.

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

    ...

  ],

...

}