Lancement de l’API Google Tag Manager V2

Google Tag Manager possède une API programmatique très astucieuse qui vous permet de faire presque tout ce qui est également possible dans l’interface utilisateur GTM. J’ai beaucoup utilisé l’API, notamment pour mes outils GTM, qui pourraient également recevoir une nouvelle version bientôt !

L’API a récemment été mise à jour vers sa deuxième version (V2), et dans cet article, je souhaite passer en revue les ajouts, suppressions et modifications introduits par la nouvelle version.

Tout d’abord, la V1 de l’API est toujours entièrement fonctionnelle, vous n’avez donc pas besoin de migrer tant que vous n’êtes pas prêt. Cela étant dit, la nouvelle version apporte un certain nombre de changements qui, je suis sûr, vous seront utiles lorsque vous travaillerez avec l’API.

Changements les plus importants

Le changement le plus important, à mon avis, est l’introduction de espace de travail comme point central dans presque toutes les interactions avec quoi que ce soit au niveau du conteneur. Ce n’est pas seulement qu’il existe un nouvel espace de noms pour les espaces de travail dans l’API, mais que vous devez toujours référencer un espace de travail lorsque vous interagissez avec des actifs de conteneur. Cela va être le plus grand obstacle dans une migration, je crois. Tout ce qui se passe dans un espace de travail (à peu près toutes les interactions de l’interface utilisateur avec un seul brouillon de conteneur) doit désormais être accompagné de l’ID de l’espace de travail que vous souhaitez modifier. Ceci, à son tour, signifie un aller-retour via l’API des espaces de travail pour obtenir les identifiants dont vous avez besoin.

Un autre changement très visible est la séparation des Variables intégrées dans son propre espace de noms. Heureusement, il existe également un simple raccourci de traitement par lots pour activer/supprimer plusieurs variables intégrées en une seule requête.

Sur le plan technique, lorsque vous utilisez des bibliothèques clientes, vous fournissez désormais le chemin d’accès à l’actif en tant que paramètre unique (essentiellement path ou alors parent) au lieu d’utiliser plusieurs paramètres nommés. Les nouvelles représentations des ressources incluent les path key, que vous pouvez ensuite utiliser pour enchaîner facilement les commandes de l’API.

Enfin, et j’adore ça, il y a un support pour ajouter Remarques à pratiquement toutes les ressources disponibles via l’API. Même si l’interface utilisateur ne prend pas encore en charge le Remarques champ aussi largement, vous pouvez désormais ajouter un texte descriptif à tous les actifs via l’API. Très utile pour documenter le conteneur.

(METTRE À JOUR: peu de temps après avoir écrit cet article, GTM a publié prise en charge des notes dans l’interface utilisateur aussi, youpi !)

Modifications détaillées

Ce qui suit est une présentation de tous les espaces de noms dans la nouvelle version de l’API, avec des informations sur ce qui a changé depuis la V1.

1. Comptes

Changements de ressources : La ressource Comptes a les éléments suivants Nouveau des champs:

• path: chemin du compte, par exemple accounts/12345
• tagManagerUrl: URL directe vers votre compte dans l’API GTM

Changements de méthode : Il n’y a pas de changements significatifs dans les méthodes des comptes.

2. Variables intégrées

Il s’agit d’un tout nouvel espace de noms dans l’API. Au lieu de transmettre une liste de variables intégrées dans la ressource de conteneur elle-même, vous devez maintenant activer explicitement les variables intégrées dans l’espace de travail de votre choix. Vous pouvez lire la description complète de cette nouvelle fonctionnalité ici.

Notez que si vous souhaitez activer plusieurs variables intégrées dans une seule requête (fortement recommandé), vous pouvez utiliser un format de lot abrégé pour le faire.

accounts()     .containers()     .workspaces()     .built_in_variables()     .create(         parent='accounts/%s/containers/%s/workspaces/%s' % (accountId, containerId, workspaceId),         type=['clickClasses', 'clickElement', 'clickId', 'clickUrl', 'clickText', 'clickTarget'] )

3. Conteneurs

Changements de ressources : L’espace de noms Containers n’a pas beaucoup changé. Les Nouveau les champs sont les mêmes que pour les comptes : path et tagManagerUrl. Les champs qui étaient supprimé de V2 sont les redondants timeZoneCountryId et timeZoneId. Les enabledBuiltInVariable a été remplacé par l’espace de noms Built-in Variables introduit ci-dessus.

Changements de méthode : Il n’y a pas de changements significatifs dans les méthodes Containers.

4. Environnements

Changements de ressources : Les principales modifications apportées à la ressource Environnements sont les suivantes :

• path: chemin relatif dans l’API vers l’environnement donné

• authorizationTimestamp: prend en charge les deux nanos et seconds comme valeurs

• workspaceId: lien pour prévisualiser un espace de travail donné dans l’environnement

• tagManagerUrl: lien vers la page Environnements dans le conteneur

Changements de méthode: Le changement le plus important est que l’ancien environments.reauthorize_environments l’espace de noms a été supprimé au profit de l’ajout simple d’un reauthorize() méthode à l’API Environments principale.

5. Dossiers

Changements de ressources : Les grands changements apportés à la ressource Dossiers sont :

• path: chemin API relatif vers le dossier

• workspaceId: ID de l’espace de travail à partir duquel le dossier a été récupéré

• tagManagerUrl: lien vers le dossier dans l’interface GTM

• notes: notes sur le dossier

Changements de méthode : Les principaux changements apportés aux méthodes sont que les deux folders.entities et folders.move_folders ont été remplacés par leurs propres méthodes d’API dédiées dans entities() et move_entities_to_folders()respectivement.

Il y a aussi une nouvelle méthode, revert()qui vous permet d’annuler les modifications apportées à un dossier dans l’espace de travail donné.

6. Balises

Changements de ressources : Les seuls changements sont l’inclusion de path, workspaceId et tagManagerUrl. Sinon, la représentation des ressources est restée relativement inchangée.

Changements de méthode : Le seul grand changement est l’introduction de la revert() qui vous permet d’annuler toute modification de la balise dans l’espace de travail donné.

7. Déclencheurs

Les déclencheurs ont été affectés exactement de la même manière que les balises. Les changements sont identiques, à l’exception de notes désormais également introduit comme champ inscriptible pour les déclencheurs.

8. Autorisations utilisateur

(Remarque, cela s’appelait uniquement les autorisations dans la documentation de la version précédente de l’API.)
Changements de ressources : Les principales modifications apportées aux autorisations utilisateur sont :

• path: chemin API relatif vers l’entité d’autorisation, inclut le permissionId

• accountAccess.permission: maintenant une chaîne plutôt qu’une liste/un tableau

• containerAccess[].permission: maintenant une chaîne plutôt qu’une liste/un tableau

Changements de méthode : Pas de changements significatifs dans les méthodes.

8. variables

Les modifications apportées aux variables sont à peu près équivalentes à celles apportées aux balises, alors consultez la section correspondante ci-dessus pour plus de détails.

9. En-têtes de version

L’API Version Headers est un nouvel ajout à l’API GTM. Fondamentalement, c’est un raccourci pour accéder aux versions d’un conteneur donné. Contrairement à l’API Versions elle-même, Version Headers ne renvoie que, surprise surprise, des en-têtes. Cela maintient les appels d’API vraiment légers et vous permet d’obtenir rapidement les informations nécessaires, telles que l’ID de version.

Vous pouvez consulter la documentation pour plus de détails sur la représentation des ressources.

L’API a deux méthodes.

• latest() renvoie l’en-tête de version de la dernière version du conteneur. La dernière version est la version la plus récemment créée dans Google Tag Manager et est très pertinente pour les espaces de travail, car les espaces de travail doivent être synchronisés avec la dernière version du conteneur avant de pouvoir être publiés ou transformés en versions eux-mêmes.

• list() renvoie une liste de toutes les versions de conteneur dans un conteneur donné.

10. Versions

(Notez que cela s’appelait auparavant Versions de conteneur dans la documentation de la version précédente de l’API.)
Changements de ressources : Voici les modifications apportées aux versions dans l’API GTM :

• path: chemin API relatif vers la version du conteneur

• description: s’appelait autrefois notes dans la version précédente de l’API

• builtInVariable: liste des variables intégrées activées dans la version

• tagManagerUrl: lien vers la version du conteneur dans l’interface utilisateur GTM

Notez que le macro et rule les paramètres sont obsolètes dans la nouvelle version de l’API.

Changements de méthode: Voici les principaux changements apportés aux méthodes Versions :

• create(): obsolète – la création de la version du conteneur se fait via Workspaces

• list(): obsolète – la liste des versions se fait maintenant via les en-têtes de version

• live(): récupère la version du conteneur actuellement en ligne dans le conteneur

• set_latest(): définit la version donnée comme la dernière version dans le conteneur – remplace restore() dans la version précédente de l’API

11. Espaces de travail

Les API des espaces de travail a été introduit dans la V2 de l’API GTM. Vous voudrez certainement suivre ce lien et vous familiariser avec la nouvelle API. Comprendre le fonctionnement des espaces de travail dans le conteneur est essentiel pour comprendre le fonctionnement de l’API GTM.

• create_version() crée une version à partir d’un espace de travail, mais uniquement si la version passe tous les contrôles de syntaxe et de validation de GTM.

• getStatus() renvoie toutes les entités en conflit et/ou modifiées dans l’espace de travail. Ceci est utile si vous souhaitez vérifier si l’espace de travail est prêt à être transformé en une version.

• resolve_conflict() permet de résoudre les conflits en faveur de l’espace de travail ou de la dernière version.

• sync() vous permet de synchroniser l’espace de travail avec la dernière version du conteneur – une étape nécessaire à franchir avant de créer la version.

Les espaces de travail sont fondamentaux pour de nombreuses interactions avec l’API. Fondamentalement, lorsque vous travaillez avec des balises, des déclencheurs, des variables, des dossiers et des variables intégrées, vous devez toujours fournir l’ID de l’espace de travail avec lequel vous interagissez. Il n’y a plus de « projet de conteneur » unique. Il y a toujours un espace de travail dans lequel vous travaillez.

En plus de devoir mettre à jour vos méthodes, cela signifie également que vous devez repenser certains des flux d’API que vous avez utilisés jusqu’à présent. Par exemple, au lieu de simplement créer de nouveaux éléments dans un conteneur, vous devez maintenant spécifier l’espace de travail avec lequel vous souhaitez travailler. Cela signifie que vous devrez peut-être d’abord list() les espaces de travail disponibles pour obtenir l’ID que vous recherchez. Ou peut-être voulez-vous create() un nouvel espace de travail pour ne pas gâcher le travail inachevé des autres.

Résumé

La nouvelle API a certainement beaucoup de choses à comprendre. L’introduction d’espaces de travail, pour sa part, est certaine de rendre la migration un peu un casse-tête. Cependant, il serait tout aussi gênant de travailler avec une API qui n’est pas synchronisée avec l’ensemble de fonctionnalités de l’interface utilisateur qu’elle gère. Pour cette raison, je pense qu’il est très logique de passer à la dernière version de l’API dès que possible.

La plupart des choses sont faciles à comprendre, comme comment passer de accountId= et containerId= pour path=accounts/accountId/containers/containerId. En fait, je pense que des changements comme celui-ci facilitent le travail avec les langages de programmation qui utilisent l’interpolation de chaînes (Python, par exemple). Certaines conventions peuvent prendre du temps à comprendre de manière routinière, telles que la façon d’utiliser versionheaders.list au lieu de versions.list.

Une chose qui est une demande constante de fonctionnalité de ma part est que Google mettrait à jour ses messages d’erreur. Il est très difficile de comprendre ce qui ne va pas lorsque tout ce que vous voyez dans les journaux est “400 Bad Request” ou “500 Backend Error”.

Que pensez-vous de la nouvelle API ? Avez-vous écrit des outils pour l’API GTM que vous souhaitez partager ? Je vous en prie!