Provisionnement de comptes gérés par l'utilisateur – Guide du développeur de l'API

Ce document explique les concepts importants liés à l'utilisation de l'API de gestion des comptes pour créer des comptes Google Analytics.

Présentation

Vous pouvez utiliser l'API de provisionnement pour créer des comptes Google Analytics et activer Google Analytics pour vos clients à grande échelle. Elle est destinée aux fournisseurs de services qualifiés et aux grands partenaires. Consultez la présentation de l'API de provisionnement pour plus d'informations sur l'API de provisionnement.

Avant de commencer

Toutes les API Google Analytics sont accessibles de la même manière. Avant de commencer à utiliser l'API de provisionnement, vous devez:

  • Consultez la page Bibliothèques clientes pour obtenir la liste complète des bibliothèques clientes spécifiques aux langages de programmation qui fonctionnent avec l'API.
  • Consultez le Guide de référence pour en savoir plus sur l'interface API et découvrir comment accéder aux données sans bibliothèque cliente.

Chaque bibliothèque cliente fournit un seul objet de service d'analyse permettant d'accéder à l'API de provisionnement. Pour créer l'objet de service, vous devez généralement procéder comme suit:

  1. Enregistrez votre application dans la console Google APIs.
  2. Autorisez la création d'un compte Google Analytics.
  3. Créez un objet de service Analytics.

Si vous n'avez pas effectué ces étapes, veuillez lire le tutoriel API Hello Google Analytics. Ce didacticiel va vous guider à travers les premières étapes de la création d'une application API Google Analytics. Vous saurez ensuite comment accéder aux API Google Analytics pour effectuer des tâches concrètes.

Présentation

Lorsque vous créez des comptes Google Analytics à l'aide de l'API de provisionnement, vous devez prendre en compte deux flux distincts:

  • Flux technique: procédure complète permettant de provisionner de manière automatisée un compte Google Analytics pour un utilisateur.
  • Flux utilisateur: considérations d'implémentation à prendre en compte pour le flux de création de compte du point de vue de l'utilisateur.

Ce document décrit les étapes et les exigences générales pour chaque flux.

Flux technique

Pour créer un compte et l'intégrer à Google Analytics à l'aide de l'API de gestion des comptes, procédez comme suit:

  1. Invitez l'utilisateur à authentifier et autoriser l'application ou le service à l'aide d'OAuth 2.0.
  2. Créez une demande de compte à l'aide de l'API de provisionnement.
  3. Redirigez l'utilisateur pour qu'il accepte les conditions d'utilisation de Google Analytics et qu'il gère la réponse.
  4. (Facultatif) Configurez le compte et les opportunités d'intégration.

Une fois toutes ces étapes effectuées, un compte Google Analytics est créé pour l'utilisateur. Vous disposez alors de l'ID de compte, de l'ID de la propriété et de l'ID de la vue (de profil) correspondant.

Chaque étape ci-dessous comporte des exigences, des résultats et une description du flux technique.

1. Authentification et autorisation

Chaque utilisateur doit autoriser votre application et lui donner la possibilité de provisionner un compte Google Analytics en son nom. Le flux d'application Serveur Web OAuth 2.0 est suggéré pour effectuer cette étape.

Ce dont vous avez besoin pour effectuer cette étape

Le résultat de cette étape

Une fois le flux OAuth 2.0 terminé, l'utilisateur aura autorisé votre application à provisionner un compte en son nom, et vous obtiendrez un jeton d'accès pour l'utilisateur.

Remarque sur les jetons et les niveaux d'accès:

  • Si vous avez l'intention d'envoyer des demandes supplémentaires pour la configuration du compte utilisateur ou les données de rapport après la création du compte, vous pouvez également autoriser des champs d'application supplémentaires au cours de cette étape. Par exemple, les champs d'application readonly ou edit.
  • Les jetons d'accès ont une durée de vie limitée. Si votre application a besoin d'accéder à l'API Google Analytics au-delà de la durée de vie d'un jeton d'accès, vous pouvez également demander un jeton d'actualisation en définissant access_type=offline. Un jeton d'actualisation doit être enregistré dans un espace de stockage à long terme sécurisé pour chaque utilisateur, car il permet à votre application d'obtenir de nouveaux jetons d'accès. Pour en savoir plus, consultez la section Accès hors connexion.

Flux technique pour cette étape

Vous devez obtenir un jeton d'accès pour l'utilisateur. En fonction du flux décrit sur la page Serveur Web OAuth 2.0, redirigez l'utilisateur vers le service Google Accounts, puis gérez la réponse lorsque l'utilisateur est redirigé vers votre service après avoir terminé le flux d'authentification.

Indiquez l'URL OAuth 2.0 à laquelle l'utilisateur doit accéder.

Lorsque l'utilisateur clique sur un bouton ou un lien pour commencer ou créer un compte, le lien doit pointer vers le début du flux OAuth 2.0 pour demander à l'utilisateur d'accorder des autorisations de provisionnement. Exemple :

https://accounts.google.com/o/oauth2/auth?
  scope=https://www.googleapis.com/auth/analytics.provision
  &redirect_uri={YOUR REDIRECT URI for OAUTH}
  &response_type=code
  &client_id={YOUR CLIENT ID}
Gérer la réponse du service Comptes Google

Une fois que l'utilisateur a pris sa décision d'accorder l'accès à votre application, il est redirigé vers redirect_uri, comme spécifié dans l'URL que vous avez créée avec un paramètre de requête contenant un code d'autorisation. Si l'utilisateur a approuvé la requête, la réponse du code d'autorisation peut être utilisée pour échanger le code d'autorisation contre un jeton d'accès en envoyant une requête POST à l'API Google Accounts.

Enregistrez le jeton d'actualisation (le cas échéant).

Le jeton d'accès sera utilisé à l'étape suivante pour que vous puissiez le stocker temporairement. Si vous avez également demandé un jeton d'actualisation pour l'utilisateur, vous devez le stocker de manière sécurisée pour une utilisation à plus long terme. Un jeton d'actualisation a une longue durée de vie et peut être utilisé pour émettre de nouveaux jetons d'accès.

2. Créer un ticket de compte à l'aide de l'API de provisionnement

Une fois que vous disposez d'un jeton d'accès pour l'utilisateur autorisé, vous pouvez l'utiliser pour envoyer une requête à l'API de provisionnement afin de créer un ticket de compte pour l'utilisateur. La demande d'accès au compte est la première étape de la création d'un compte pour un utilisateur.

Ce dont vous avez besoin pour effectuer cette étape

Un jeton d'accès pour l'utilisateur autorisé, comme décrit dans la section Authentification et autorisation, ainsi que les informations de provisionnement suivantes:

  • URI de redirection
    • Définit la page vers laquelle l'utilisateur est redirigé après la page des conditions d'utilisation de Google Analytics. Il peut être différent de l'URI de redirection spécifié lors du flux d'autorisation OAuth 2.0.
    • La valeur du paramètre URI de redirection doit correspondre exactement à l'une des valeurs enregistrées dans la Google Developers Console (y compris les schémas http ou https, la casse et le caractère "/" de fin).
  • Champs de compte
    • Une propriété name est obligatoire pour le compte.
  • Champs du site Web
    • Une propriété name est obligatoire pour la propriété.
    • Un élément websiteUrl est obligatoire.
  • Champs de profil
    • Une propriété name est obligatoire pour le profil.
    • Un élément timezone peut être fourni (facultatif). La valeur par défaut est America/Los_Angeles.

Lors de la création d'une demande d'assistance pour un compte, seuls les champs de base identifiés ci-dessus peuvent être définis. Une fois le compte créé, toute modification de configuration supplémentaire de la propriété ou de la vue (profil) peut être effectuée à l'aide de l'API Management.

Pour en savoir plus sur ces champs, consultez la documentation de référence de l'API pour les comptes, les propriétés et les vues (profils).

Le résultat de cette étape

Une fois que la requête aboutit à l'API de provisionnement, vous disposez d'un ticket de compte de courte durée pour l'utilisateur. L'ID de ticket du compte est utilisé à la dernière étape pour inviter l'utilisateur à accepter les conditions d'utilisation et à activer son compte. Le compte ne peut pas être utilisé tant que les conditions d'utilisation n'ont pas été acceptées.

Flux technique pour cette étape

En utilisant le jeton d'accès de l'utilisateur obtenu lors de l'authentification et l'autorisation, une requête HTTP POST est envoyée à l'API de gestion des comptes.

Requête d'API de provisionnement pour créer un ticket de compte

Examinez la méthode createAccountTicket dans la documentation de référence de l'API de provisionnement pour savoir comment envoyer la requête.

Réponse de l'API de gestion des comptes

Une requête réussie renvoie une réponse 200. Le corps de la réponse contient un ticket de compte, qui est de courte durée. Le ticket de compte se compose d'un ID et des détails de la nouvelle arborescence de compte.

Consultez le Account Ticket resource dans la documentation de référence de l'API de provisionnement pour plus de détails sur la réponse.

Les réponses d'erreur doivent également être gérées par l'application.

3. L'utilisateur accepte les conditions d'utilisation de Google Analytics.

Une fois que vous disposez d'un ID de ticket de compte pour l'utilisateur, vous pouvez l'utiliser avec la requête des conditions d'utilisation pour inviter l'utilisateur à accepter les conditions d'utilisation de Google Analytics.

Ce dont vous avez besoin pour effectuer cette étape

L'ID de la demande du compte de l'utilisateur autorisé.

Le résultat de cette étape

Une fois le flux des conditions d'utilisation rempli à l'aide de l'ID de ticket du compte, le compte, la propriété et la vue (profil) seront créés. L'utilisateur dispose désormais d'un compte actif. La réponse de la page des conditions d'utilisation inclura l'ID de compte, l'ID de propriété et l'ID de vue (de profil).

Flux technique pour cette étape

À l'aide de l'ID de ticket du compte, redirigez l'utilisateur vers la page des conditions d'utilisation de Google Analytics où il peut les accepter. Vous devez ensuite gérer la réponse de l'API.

Indiquez l'URL des conditions d'utilisation à laquelle l'utilisateur doit accéder.

Redirigez l'utilisateur vers la page des conditions d'utilisation en incluant l'ID de ticket du compte dans l'URL:

https://analytics.google.com/analytics/web/?provisioningSignup=false#/termsofservice/{account_ticket_id}
Gérer la réponse des conditions d'utilisation

Une fois que l'utilisateur a effectué une action sur la page des conditions d'utilisation, il est redirigé vers le redirectUri spécifié lors de la création de la demande d'assistance. La réponse de la page des conditions d'utilisation sera incluse dans la chaîne de requête.

Les réponses Réussies renvoient des données sur la structure de compte nouvellement créée ainsi que sur le accountTicketId d'origine:

https://{YOUR REDIRECT URI for TOS}?
  accountId={accountId}
  &webPropertyId={webPropertyId}
  &profileId={profileId}
  &accountTicketId={accountTicketId}

Par exemple, si le gestionnaire des conditions d'utilisation de votre application est défini sur http://www.your-app.com/gaTOS, il doit être défini sur redirectUri lors de la création de tickets de compte. Le gestionnaire des conditions d'utilisation de votre application doit s'attendre à ce que les requêtes HTTP GET contenant les paramètres de requête accountId, webPropertyId, profileId et accountTicketId soient traitées correctement, et les gérer correctement pour les cas où la demande d'assistance est valide et que l'utilisateur les a acceptées.

Les réponses Échec incluent le message d'erreur suivant:

https://{YOUR REDIRECT URI for TOS}?
  error={error_code}
  &accountTicketId={accountTicketId}

Votre gestionnaire de conditions d'utilisation doit également gérer correctement les requêtes HTTP GET contenant un paramètre de requête error, indiquant un problème. La valeur du paramètre de requête peut être utilisée pour effectuer d'autres actions ou afficher un message:

  • error=user_cancel : l'utilisateur n'a pas accepté les conditions d'utilisation.
  • error=max_accounts_reached : l'utilisateur a atteint la limite de comptes Google Analytics.
  • error=backend_error : erreur générale. Le serveur a renvoyé une erreur ne relevant pas des catégories ci-dessus.

4. (Facultatif) Opportunités d'intégration

Si vous avez suivi le flux technique ci-dessus, vous avez créé un compte pour l'utilisateur, avec l'ID de compte, l'ID de la propriété et l'ID de la vue (profil). Si vous avez également demandé des autorisations supplémentaires, vous pouvez également disposer d'un jeton d'actualisation pour l'utilisateur. Grâce à ces données, vous pouvez:

  • Le cas échéant, injectez automatiquement l'extrait de suivi Google Analytics standard avec l'ID de propriété du nouveau compte pour chaque page du site Web de l'utilisateur.
  • Configurer automatiquement la propriété de l'utilisateur à l'aide de l'API Management
  • Fournissez des rapports à l'utilisateur dans votre produit (dans le panneau d'administration, par exemple) à l'aide de l'API Embed ou de l'API Core Reporting.

Parcours utilisateur

Cette section décrit les considérations d'implémentation liées aux étapes du flux de création de compte du point de vue de l'utilisateur.

Le parcours commence lorsque l'utilisateur propose les deux options suivantes pour activer Analytics pour sa propriété:

  1. Créer un compte Google Analytics
  2. Utiliser un compte Google Analytics existant (Remarque: Cette procédure n'est pas traitée dans ce document. consultez l'API Management pour savoir comment accéder aux données de configuration Google Analytics d'un utilisateur.)

Lorsque vous créez un compte Google Analytics, vous devez envoyer des informations avec la demande de provisionnement, telles que le nom du compte, le nom de la propriété, etc. En fonction des informations dont vous disposez sur l'utilisateur et du parcours que vous souhaitez lui présenter, il existe trois options principales pour lancer le flux utilisateur après qu'il a cliqué sur "Créer un compte":

Demander les informations sur le compte après l'autorisation

Dans ce cas, l'utilisateur est invité à fournir des informations sur le compte au milieu du processus. Le flux se présente comme suit:

  1. L'utilisateur est redirigé vers le service de compte Google pour le flux OAuth 2.0. Si l'utilisateur ne possède pas de compte Google ou s'il n'est pas connecté, il sera invité à créer un compte Google ou à se connecter.
  2. L'utilisateur est invité à autoriser l'application à créer des comptes Google Analytics.
  3. L'utilisateur accepte les demandes d'autorisations pour l'application.
  4. L'utilisateur est redirigé vers le fournisseur de services. Notez que si l'utilisateur refuse l'autorisation, il est tout de même redirigé vers le fournisseur de services.
  5. Un formulaire est présenté à l'utilisateur pour recueillir des informations sur le compte à créer (par exemple, le nom du compte, le nom de la propriété, le nom du profil, le fuseau horaire, l'URL du site Web, etc.).
  6. L'utilisateur remplit et envoie le formulaire, puis est redirigé vers Google/qui affiche les conditions d'utilisation de Google Analytics.
  7. L'utilisateur accepte les conditions d'utilisation.
  8. L'utilisateur est redirigé vers le fournisseur de services. Un message de confirmation s'affiche indiquant qu'il a bien créé un compte Google Analytics avec des informations sur ce compte et comment y accéder. Notez que si l'utilisateur n'accepte pas les conditions d'utilisation, il est tout de même redirigé vers le fournisseur de services.

Demander les informations sur le compte avant l'autorisation

Dans ce cas, l'utilisateur est invité à l'avance à fournir les détails de configuration du compte sur le point d'être créé. Le flux se présente comme suit:

  1. Sur le site du fournisseur de services, un formulaire est présenté à l'utilisateur pour recueillir des informations sur le compte à créer (par exemple, le nom du compte, le nom de la propriété, le nom du profil, le fuseau horaire, l'URL du site Web).
  2. L'utilisateur remplit le formulaire, puis clique sur "Envoyer" et est redirigé vers le service de compte Google pour le flux OAuth 2.0. Si l'utilisateur ne possède pas de compte Google ou s'il n'est pas connecté, il sera invité à créer un compte Google ou à se connecter.
  3. L'utilisateur est invité à autoriser l'application à créer des comptes Google Analytics.
  4. L'utilisateur accepte les autorisations demandées pour l'application.
  5. L'utilisateur est redirigé vers le fournisseur de services.
  6. L'utilisateur est redirigé vers Google/les conditions d'utilisation de Google Analytics s'affichent.
  7. L'utilisateur accepte les conditions d'utilisation.
  8. L'utilisateur est redirigé vers le fournisseur de services. Un message de confirmation s'affiche indiquant qu'il a bien créé un compte Google Analytics avec des informations sur ce compte et comment y accéder.

Préremplir les détails du compte ou ignorer des formulaires

Si des informations sur le compte utilisateur sont déjà disponibles (par exemple, l'URL du site Web, le nom du site Web, le fuseau horaire, etc.), les deux options ci-dessus peuvent être encore simplifiées comme suit:

  • Le préremplissage du formulaire et la possibilité pour l'utilisateur de le modifier s'il le souhaite
  • Ignorer complètement l'étape du formulaire et créer automatiquement le compte à l'aide des informations existantes.