Ce que contient un plan de marquage, et ce qu'il ne peut pas détecter

Qu'est-ce qu'un plan de marquage ?

En analytique produit, un plan de marquage est la spécification écrite qui liste chaque événement envoyé par un produit, le moment exact où chacun se déclenche, les propriétés qu'il transporte avec leurs types, la source qui l'émet et la personne qui en est responsable, le tout validé avant que quiconque écrive le code d'instrumentation. La documentation Protocols de Segment le définit comme "a data spec outlining the events and properties you intend to collect across your Segment Sources." La version d'Amplitude ajoute la raison d'être de chaque ligne : "A tracking plan defines every event and property you collect, why you collect each one, and which source emits it."

Le plan est le contrat et le code de tracking en est l'implémentation. Quand les deux divergent, quelqu'un doit décider lequel a tort, et sans plan il n'existe rien contre quoi vérifier le code. Le suivi des événements consiste à enregistrer ce que les utilisateurs ont fait. Le plan de marquage est le document qui dit ce que "a fait" signifie pour chaque événement.

De quelles colonnes un plan de marquage a-t-il besoin ?

Un plan de marquage a besoin d'une ligne par événement et d'assez de colonnes pour qu'un ingénieur puisse implémenter l'événement sans poser une seule question. Les colonnes ci-dessous sont celles qui évitent de vraies disputes plus tard. L'éditeur de Tracking Plan de Segment en utilise une partie, nommées Name, Description, Status, Data Type et Permitted Values.

La liste des types de données de Segment constitue une valeur par défaut raisonnable pour la colonne Type : "any, array, object, boolean, integer, number, string, null, Date time", les dates-heures étant "required to be in ISO-8601 format." Sa colonne Permitted Values accepte des "simple regular expressions to validate property values", ce qui ne fonctionne que sur les propriétés de type string.

À quoi ressemble une ligne remplie d'un plan de marquage ?

Une ligne remplie se lit comme une petite spécification. Voici un événement tiré d'un parcours d'inscription SaaS, écrit tel que le contiendrait un plan stocké dans un dépôt de code :

event: signup_completed
trigger: >
  Fires once, from the server, after the account row is written.
  Not on button click. Not on page load of /welcome.
answers: Signup-to-activation funnel, weekly signups by channel
source: backend
owner: growth-eng
status: live
properties:
  plan:
    type: string
    required: true
    allowed: [team, pro]
  signup_method:
    type: string
    required: true
    allowed: [email, google, github]
  invited:
    type: boolean
    required: false

Le texte du déclencheur est la partie que la plupart des plans ratent. "Se déclenche à l'inscription" ne dit pas si une soumission de formulaire échouée compte, si une nouvelle tentative déclenche l'événement deux fois, ni si l'événement vient du navigateur ou du serveur. Écrire "not on button click" écarte le doublon le plus courant, celui où le clic déclenche l'événement avant que le serveur ne rejette le formulaire. Le style de nommage est un choix distinct, et choisir une convention de nommage des événements avant la première ligne évite un renommage plus tard.

Que peut valider un outil de plan de marquage, et que ne peut-il pas valider ?

Un outil de plan de marquage valide les événements qui arrivent par rapport aux événements décrits dans le plan, et il ne peut rien vous dire des événements qui n'arrivent jamais. Cette seconde moitié est la chose la plus utile à savoir sur ces outils, et les éditeurs le disent eux-mêmes.

La documentation de Segment décrit le côté vérification : "Violations generate when an event doesn't match the spec'd event in the Tracking Plan." Puis, dans la description de la colonne Status : "You can't require a Track call because Segment is unable to verify when a Track call should be fired." Segment peut vérifier qu'un événement porte ses propriétés obligatoires, mais il n'a aucun moyen de savoir que l'événement aurait dû se déclencher et ne l'a pas fait.

Amplitude traite la direction opposée. Les événements qui arrivent sans figurer dans le plan apparaissent comme "Unexpected", et Amplitude précise : "You can add them to your plan, or delete them to stop ingestion and remove them from your data catalog." Pour la direction manquante, Amplitude publie un guide distinct intitulé "Planned events that never arrived: confirm the problem", dont la consigne est la suivante : "Compare your tracking plan with observed data and your planning records to find planned events that never reached Amplitude." La même page indique que "Data Assistant doesn't identify these entries" et qu'Observe, la vue qui montre si un événement est arrivé, couvre "the selected time range, up to 14 days."

Un tableau de bord de validation au vert signifie donc que chaque événement arrivé correspondait à sa spécification. Il ne signifie pas que chaque événement de la spécification arrive. La solution pratique est une vérification à chaque mise en production. Listez les événements marqués en production dans le plan, interrogez les données récentes pour chaque nom et signalez ceux dont le compte est nul. Le guide d'Amplitude ajoute la bonne précaution : un événement sans activité "might belong to a rare workflow, a disabled feature, or a future release", alors interrogez le responsable avant de supprimer la ligne.

Quelles limites des destinations doivent figurer dans le plan ?

Les limites de chaque outil vers lequel les événements circulent ont leur place dans le plan, car une ligne qui dépasse une limite échoue en silence dans la destination. Google Analytics le dit clairement : "Google Analytics doesn't log events, event parameters, and user properties that exceed the following limits."

Les deux outils échouent différemment quand un plan les dépasse. GA4 abandonne l'élément, et son exemple est le suivant : "Analytics doesn't process the 26th user property nor does it process an event name with more than 40 characters." Amplitude continue l'ingestion mais "stops indexing new values", si bien que les données existent dans les exports sans pouvoir être interrogées dans les graphiques. Amplitude ajoute que les événements au-delà de sa limite de types d'événements "still count toward the monthly event volume", ce qui signifie qu'un bug d'instrumentation incontrôlé coûte de l'argent pour des données que personne ne peut afficher dans un graphique.

Segment a sa propre limite pour les plans gérés sous forme de fichiers : un CSV de Tracking Plan importé "must be smaller than 15 mb" et doit "have fewer than 100,000 rows and 2,000 rules."

Combien d'événements la première version doit-elle contenir ?

La première version doit contenir les quelques événements qui répondent aux questions que l'équipe pose déjà chaque semaine, et rien d'autre. Le guide d'implémentation d'Amplitude recommande de "resist the urge to track everything upfront" et suggère ceci : "starting with two important events in your product to give you initial insights." Son guide de taxonomie ordonne le travail ainsi : d'abord les objectifs business, puis les métriques clés, puis les événements et propriétés dont ces métriques ont besoin.

Cet ordre est le bon. Partez de la métrique de la revue hebdomadaire, comme la north star metric, écrivez la question qu'elle soulève et n'ajoutez que les événements nécessaires pour y répondre. Un parcours d'inscription qui a besoin d'une analyse d'entonnoir demande un événement par étape et une propriété qui découpe le résultat, pas quarante événements pour chaque clic sur la page. Si vous utilisez Flowsery, son suivi des objectifs "enregistre inscriptions, achats, téléchargements et événements personnalisés au même endroit", et le plan est l'endroit où vous décidez lesquels de ces objectifs valent la peine d'être définis.

Comment garder un plan de marquage à jour ?

Un plan de marquage reste à jour quand une modification du code de tracking ne peut pas être fusionnée sans une modification correspondante du plan. Tout le reste n'est qu'un rappel que les gens ignorent.

La colonne Statut fait l'essentiel du travail. Marquer un événement comme obsolète au lieu de supprimer sa ligne empêche un nouvel ingénieur de réintroduire l'ancien nom six mois plus tard. Les deux outils gardent un historique. Segment indique que les modifications du plan faites par import sont "reflected in the Audit Trail and Tracking Plan changelog", et son export CSV nomme chaque fichier workspaceSlug-trackingPlanName--yyyy-mm-dd--hh-mm-utc. Un plan qui vit dans le dépôt à côté du code obtient gratuitement son historique grâce au contrôle de version.

Questions fréquentes

Quelle est la différence entre un plan de marquage et une convention de nommage des événements ?

Une convention de nommage des événements est une règle parmi d'autres dans un plan de marquage : la façon dont les noms sont formés, par exemple object_action en snake case. Le plan de marquage est la liste complète des événements qui suivent cette règle, avec pour chacun son déclencheur, ses propriétés, ses types, sa source et son responsable.

Qui doit être responsable du plan de marquage ?

Une personne nommée doit approuver les changements, issue de l'équipe qui lit le plus les données, pendant que les ingénieurs proposent des lignes. Un plan que n'importe qui peut modifier sans relecture finit dans le même état que l'absence de plan.

Un plan de marquage doit-il vivre dans un tableur ou dans un outil ?

Un tableur suffit pour une première version de quelques dizaines d'événements. Un outil comme Segment Protocols ou Amplitude Data ajoute la validation des événements entrants par rapport au plan, et un fichier dans le dépôt de code ajoute la relecture et l'historique via les pull requests.

Les événements côté serveur doivent-ils aller dans le même plan de marquage ?

Oui. Gardez un seul plan avec une colonne Source, car le même nom d'événement envoyé depuis le navigateur et depuis le serveur est compté deux fois, sauf si le plan indique lequel fait foi. La définition même du plan de marquage par Amplitude inclut "which source emits it".

Comment retrouver les événements prévus qui ne se sont jamais déclenchés ?

Comparez les événements marqués en production dans le plan avec les noms d'événements observés dans les données récentes, et signalez ceux dont le compte est nul. Segment indique ne pas pouvoir rendre un appel Track obligatoire, et Amplitude précise que son Data Assistant n'identifie pas ces entrées, donc aucun tableau de bord de validation ne signale le problème de lui-même.

L'autocapture rend-elle le plan de marquage inutile ?

Non. L'autocapture enregistre les clics et les pages vues, mais pas ce que signifiait un clic, par exemple le forfait choisi par l'utilisateur ou l'acceptation du formulaire par le serveur. Les événements qui alimentent les métriques de revenu et d'activation ont toujours besoin d'un déclencheur écrit et d'une liste de propriétés.

Que doit contenir la colonne déclencheur ?

Elle doit nommer l'unique moment où l'événement se déclenche, en mots simples, y compris ce qui ne compte pas. "Se déclenche à l'inscription" ne dit pas si un envoi échoué ou une nouvelle tentative compte, ni si l'événement vient du navigateur ou du serveur. "Se déclenche une fois, depuis le serveur, après l'écriture de la ligne du compte. Pas au clic sur le bouton" ne laisse rien à deviner.

Avec combien d'événements un plan de marquage doit-il démarrer ?

Démarrez avec les quelques événements qui répondent aux questions que l'équipe pose chaque semaine. Le guide d'implémentation d'Amplitude dit "resist the urge to track everything upfront" et suggère de commencer par deux événements importants. N'en ajoutez d'autres que lorsqu'une métrique les réclame.

Que se passe-t-il quand un plan dépasse les limites de GA4 ou d'Amplitude ?

GA4 abandonne l'élément : une 26e propriété utilisateur ou un nom d'événement de plus de 40 caractères n'est jamais traité. Amplitude continue d'ingérer les données mais cesse d'indexer les nouvelles valeurs, si bien qu'elles apparaissent dans les exports sans pouvoir être interrogées dans les graphiques. Les événements au-delà de sa limite de types d'événements comptent toujours dans le volume mensuel d'événements.

Pourquoi marquer un événement comme deprecated plutôt que supprimer la ligne ?

Une ligne deprecated empêche un nouvel ingénieur de réintroduire l'ancien nom des mois plus tard. L'historique reste aussi dans le plan. Avant de supprimer la ligne d'un événement sans activité, demandez au responsable, car il "might belong to a rare workflow, a disabled feature, or a future release".