Événements Personnalisés & Propriétés Personnalisées

Metricalp collecte les événements screen_view par défaut pour suivre les sessions, les visites de pages, etc. Cependant, vous pouvez désactiver cette collecte automatique (voir Référence API) ou vous pourriez vouloir collecter d'autres événements personnalisés tout en ayant la collecte automatique activée. Pour effectuer la collecte manuelle des 'screen_view' ou de tout événement personnalisé, il y a deux façons. Celles-ci sont via l'API JavaScript ou via les attributs de données HTML. De plus, vous pouvez envoyer des propriétés personnalisées avec ces événements. Nous décrirons les deux méthodes et les propriétés personnalisées sur cette page.

Événements Personnalisés

Tout d'abord, screen_view est un 'événement système'. Tous les autres événements sont appelés 'événements personnalisés'. Les événements personnalisés doivent être déclenchés manuellement par votre système. Nous allons maintenant montrer comment le faire. Vous pouvez également déclencher des événements screen_view manuellement par les méthodes suivantes en plus des événements personnalisés. Mais il y a un point supplémentaire important, c'est que vous pouvez autoriser chaque événement personnalisé dans votre système ou seulement certains événements. C'est à vous et c'est configurable. Vous pouvez configurer cela dans Configuration des Trackers. Par exemple, vous pouvez autoriser uniquement les événements personnalisés click_save, click_buy (screen_view est toujours autorisé par le système) et tout autre type d'événement sera ignoré. Ou simplement autoriser tous les événements personnalisés. Encore une fois, c'est à vous.

Nous allons montrer deux méthodes pour la collecte d'événements personnalisés :

1. Via l'API JavaScript

Si vous avez correctement intégré Metricalp, il ajoutera un objet nommé metricalp à l'objet global de la fenêtre. Cet objet a une méthode event que vous pouvez utiliser pour envoyer des événements personnalisés. Cette méthode prend un argument, qui est un objet. Cet objet doit contenir le champ type qui indique le nom de l'événement. Vous pouvez ajouter des propriétés personnalisées supplémentaires à cet objet. Pour les propriétés personnalisées, voir plus bas sur cette page. Exemple d'un événement personnalisé via l'API JS :

window.metricalp.event({
  type: 'click_buy',
  color: 'red'
});

De plus, comme pour les frameworks React et NextJS, nous avons des bibliothèques d'intégration personnalisées et leurs API pour la création d'événements diffèrent de cette logique pure. Consultez leurs documentations.

2. Via les attributs de données HTML

Metricalp vérifiera par défaut votre document à la recherche d'éléments avec l'attribut data-metricalp-event.

S'il y a un élément avec cet attribut de données, si c'est un élément de formulaire, il écoutera l'événement d'envoi, sinon il écoutera les événements de clic pour cet élément. Si l'événement est déclenché, un événement sera généré avec le nom de la valeur de cet attribut de données. De plus, tous les attributs de données de cet élément commençant par data-metricalp- seront ajoutés en tant que propriétés personnalisées à l'événement. Par exemple :

<button data-metricalp-event="click_buy" data-metricalp-color="red">Acheter</button>

Si un visiteur clique sur ce bouton, le même événement que dans l'exemple JS ci-dessus sera généré.

Propriétés Personnalisées

Les événements personnalisés sont très puissants pour suivre des données significatives basées sur vos besoins. Chaque événement a des données de base telles que le navigateur, le pays, l'appareil, etc. Mais vous voudrez peut-être ajouter des données supplémentaires à ces événements personnalisés (ou à l'événement screen_view). Nous appelons ces données supplémentairespropriétés personnalisées. Vous pouvez ajouter des propriétés personnalisées aux événements personnalisés via l'API JavaScript ou les attributs de données HTML. Nous allons montrer comment ajouter des propriétés personnalisées ci-dessous.

Par défaut, vous pouvez ajouter des propriétés personnalisées avec les clés custom_prop1, custom_prop2, custom_prop3, custom_prop4, custom_prop5. Nous permettons actuellement 5 propriétés personnalisées par événement, mais nous prévoyons d'augmenter ce nombre à l'avenir. Par exemple :

window.metricalp.event({
  type: "screen_view",
  custom_prop1: "red"
});

Il peut être difficile de se souvenir de quelle propriété personnalisée contient quelles données. Pour éviter cette confusion, vous pouvez définir des alias pour chaque propriété personnalisée par type d'événement. Par exemple, si vous définissez `color` comme alias pour la propriété personnalisée 1 dans la configuration du tracker pour les événements screen_view, cette propriété personnalisée sera affichée comme couleur dans votre tableau de bord pour les événements screen_view. Vous pouvez maintenant créer des événements comme suit :

window.metricalp.event({
  type: "screen_view",
  color: "red"
});

Beaucoup plus lisible, n'est-ce pas ? Mais par exemple, vous pouvez définir `username` comme alias pour la propriété personnalisée 1 dans la configuration du tracker pour les événements click_save, et ensuite cette propriété personnalisée sera affichée comme nom d'utilisateur dans votre tableau de bord pour les événements click_save.

window.metricalp.event({
  type: "click_save",
  username: "John"
});

Vous pouvez également continuer à utiliser la syntaxe custom_prop1, même si vous avez défini un alias pour cette propriété personnalisée. La beauté de cela est que ces alias sont spécifiques à chaque type d'événement. Cela vous aide à capturer des données significatives et à les afficher facilement. Dans l'exemple précédent des événements personnalisés, nous avons également montré comment ajouter des propriétés personnalisées via des attributs de données HTML : data-metricalp-color="red". La syntaxe custom_prop1 est également valide pour les attributs de données HTML : data-metricalp-custom_prop1="red", où les noms des attributs de données peuvent également contenir des tirets bas.

Comme mentionné précédemment, vous trouverez cette configuration d'alias sur la page de configuration des trackers. Pour plus d'informations sur les alias de propriétés personnalisées, consultez la page de documentation Configurer les trackers.

Enfin, si vous souhaitez ajouter automatiquement des propriétés personnalisées pour certains types d'événements, vous pouvez définir 'sharedCustomProps' comme suit :

<script>
        window.metricalp = window.metricalp || {
          queue: [],
          sharedCustomProps: {
            _global: { custom_prop3: "v1.0" },
            screen_view: {
              color: "red",
              custom_prop2: "Test",
            }
          },
          event: function (e) {
            this.queue.push(e);
          },
        };
</script>

La clé '_global' ici est une clé spéciale. C'est un conteneur générique et non un type d'événement. Si vous définissez des propriétés personnalisées dans '_global', elles seront ajoutées à tous les types d'événements. Dans l'exemple précédent, custom_prop3 sera ajoutée à tous les types d'événements. Mais custom_prop2 et color ne seront ajoutés qu'aux événements screen_view. Si vous définissez une propriété personnalisée pour un type d'événement spécifique et aussi dans _global, la propriété personnalisée spécifique à l'événement écrasera la même propriété personnalisée dans _global. Dans l'exemple précédent, color est un alias pour une propriété personnalisée. Si vous utilisez la syntaxe d'alias pour la propriété personnalisée au lieu de la syntaxe custom_prop1 dans sharedCustomProps, vous devez avoir défini cet alias pour ce type d'événement dans la configuration du tracker, sinon il sera ignoré pour les types d'événements non définis. Vous devez placer la balise de script précédente avant la balise de script Metricalp afin de pouvoir ajouter sharedCustomProps aux événements screen_view automatisés. Si vous utilisez la bibliothèque React, vous pouvez définir sharedCustomProps en tant que prop

<MetricalpReactProvider
  tid="mam123456"
  initialSharedCustomProps={{
    _global: { custom_prop3: "v1.0" },
    screen_view: { color: 'red', custom_prop2: 'Test' } 
}}>

Pour plus d'informations sur sharedCustomProps avec la bibliothèque React, consultez la documentation React et la documentation NextJS.

Vous avez maintenant appris à propos des événements personnalisés et des propriétés personnalisées. Par exemple, vous pouvez créer des événements 'erreur' lorsque votre système rencontre une erreur et ajouter des journaux d'erreurs en tant que propriétés (en plus du navigateur, des informations sur l'appareil, etc., propriétés standard automatiquement collectées). Ou vous pouvez utiliser des propriétés personnalisées pour des tests A/B. Les cas d'utilisation sont infinis, basés sur votre imagination et vos besoins.

Avec des événements personnalisés et des propriétés personnalisées, vous pouvez obtenir des informations plus approfondies sur vos visiteurs. C'est la beauté de Metricalp 💜