Intégration avec JavaScript Pur (Vanilla)

Dans cette section, nous expliquerons comment intégrer votre site web en intégrant le script de Metricalp dans votre site web. Toutes les autres bibliothèques d'intégration utilisent cette méthode en interne.

Tout d'abord, vous avez besoin de votre tid (également connu sous le nom de Tracker ID). Vous pouvez l'obtenir depuis l'écran Paramètres du Tracker / Intégrer & Partager.

Après avoir obtenu votre tid, vous êtes prêt à intégrer le script de Metricalp dans votre site web. Vous devez placer le code ci-dessous en haut de chaque page. N'oubliez pas de remplacer YOUR_TID par votre tid.

<script src="https://cdn.metricalp.com/event/metricalp.js" data-allow-localhost="true" data-tid="YOUR_TID" defer></script>

C'est tout. Metricalp commencera automatiquement à collecter des événements depuis votre site web juste après cette seule ligne. Génial, non ? 🫡

Maintenant, allons dans les détails. Le script ci-dessus a l'attribut `defer`, ce qui signifie que le script ne bloquera pas le chargement de la page, mais l'exécution du script se produira avant tout autre script sur la page qui vient après ce script. Cependant, si vous souhaitez charger le script de manière asynchrone, vous pouvez supprimer l'attribut `defer` et le remplacer par l'attribut `async`. Dans ce cas, bien que le script soit chargé de manière asynchrone, il peut y avoir un problème si vous souhaitez déclencher un événement immédiatement après le chargement de la page, car le chargement du script peut ne pas être terminé avant de déclencher l'événement. Pour résoudre ce problème et rendre tout le processus plus fluide, nous pouvons ajouter une ligne supplémentaire juste au-dessus de notre script :

<script>window.metricalp = window.metricalp || {queue: [], event: function(e){this.queue.push(e)}}</script>
<script src="https://cdn.metricalp.com/event/metricalp.js" data-allow-localhost="true" data-tid="YOUR_TID" async></script>

Nous avons maintenant remplacé `defer` par `async` et ajouté une ligne supplémentaire juste au-dessus de la ligne de notre script. Nous garantissons que chaque événement sera mis en file d'attente indépendamment du temps de chargement de notre script principal. Parce que nous collectons maintenant nos événements dans une file d'attente jusqu'à ce que notre script se charge, puis il déclenche tous les événements dans la file d'attente. Ainsi, vous pouvez déclencher des événements immédiatement après le chargement d'une page. Nous recommandons généralement ce deuxième extrait de code (nous l'utilisons dans nos bibliothèques d'intégration) car il est plus performant, sécurisé et léger pour le chargement de la page.

En fournissant l'attribut data-tid, nous avons fourni un autre attribut de données data-allow-localhost="true" car par défaut Metricalp ne collecte jamais les événements depuis localhost (127.0.0.1) pour économiser votre quota d'utilisation. Cependant, si vous intégrez pour la première fois, vous pouvez autoriser les événements localhost à des fins de test. Une fois votre intégration terminée, vous pouvez supprimer cet attribut avant de publier votre site web en production. Des informations détaillées peuvent être trouvées dans les documents d'autoriser localhost & m'exclure.

Il existe quelques options supplémentaires pour personnaliser les comportements du script Metricalp, vous pouvez tout trouver dans la référence API.

Par défaut, Metricalp commence automatiquement à collecter des événements screen_view (cela peut être désactivé avec l'option data-disable-auto-route-catch, veuillez consulter la référence API pour les détails). Cependant, si vous souhaitez déclencher manuellement un événement (screen_view ou tout autre événement personnalisé), vous pouvez utiliser la fonction window.metricalp.event ou des attributs de données personnalisés. Vous en apprendrez plus à ce sujet dans la section Événements Personnalisés & Props. Si vous déclenchez des événements personnalisés, votre script doit être chargé avant que vous ne déclenchiez l'événement. En général, c'est le cas dans les deux extraits de code ci-dessus. Mais, dans le premier scénario, si vous déclenchez l'événement avant l'appel du script avec defer, il peut y avoir une erreur. Bien que ce soit un cas limite très rare, vous pouvez utiliser le deuxième extrait de code pour être sûr à 100 %.

De plus, parfois, vous pouvez vouloir joindre automatiquement certaines propriétés personnalisées à certains (ou à tous) les événements. Vous pouvez le configurer avec la deuxième approche et définir ces propriétés jointes automatiquement dans l'objet sharedCustomProps comme suit :

<script>
      window.metricalp = window.metricalp || {
          queue: [],
          sharedCustomProps: {
            _global: { custom_prop1: "Test1" },
            screen_view: {
              logged_in: 'not_logged_in',
              custom_prop2: "Test2",
            }
          },
          event: function(e){this.queue.push(e)}
      }
</script>
<script src="https://cdn.metricalp.com/event/metricalp.js" data-allow-localhost="true" data-tid="YOUR_TID" async></script>

_global est une clé spéciale pour joindre certaines propriétés à tous les événements. Gardez à l'esprit que, si vous joignez une propriété personnalisée via un alias, cet alias doit être défini pour les événements cibles dans les Paramètres du Tracker; sinon, il sera ignoré pour cet événement. Vous pouvez toujours utiliser la syntaxe custom_prop1 pour tout événement. Encore une fois, vous pouvez obtenir des informations plus détaillées sur sharedCustomProps dans la section Événements Personnalisés & Props. Si vous utilisez la bibliothèque React pour intégrer Metricalp avec React / NextJS, vous pouvez consulter la documentation de React et NextJS pour apprendre comment vous pouvez configurer sharedCustomProps dans votre application React / NextJS.