Intégration avec React

Sans aucun doute, React est l'un des frameworks frontend les plus célèbres de nos jours. Chez Metricalp, nous sommes ravis d'avoir une bibliothèque d'intégration officielle pour React et NextJS. Si vous utilisez NextJS, consultez la documentation d'intégration de NextJS. Si vous utilisez React, vous êtes au bon endroit. Commençons!

Notre bibliothèque d'intégration sur NPM s'appelle @metricalp/react

Installation

Vous pouvez l'installer comme suit:

yarn add @metricalp/react

ou

npm install @metricalp/react

Intégration

Au niveau supérieur de votre application dans src/index.js | src/main.tsx (Vite) | App.js, enveloppez votre application avec MetricalpReactProvider. Donnez ensuite votre tid (alias TrackerID) comme prop au provider. En gros, c'est tout, Metricalp commencera automatiquement à collecter tous les événements de visite et de changement de route. Mais vous pouvez personnaliser les comportements avec les props. Nous allons tout expliquer.

Exemple (projet React démarré avec Vite)

Dans src/main.tsx, importez la bibliothèque import { MetricalpReactProvider } from '@metricalp/react';. Ensuite, enveloppez votre application avec <MetricalpReactProvider allowLocalhost tid="YOUR_TID">

N'OUBLIEZ PAS de remplacer le prop tid par votre tid.

Nous avons ajouté allowLocalhost parce que, par défaut, Metricalp ne fonctionne pas sur localhost pour protéger vos limites de quota. Nous avons permis localhost à des fins de test. Vous souhaiterez le supprimer après l'avoir testé une fois pour économiser votre quota. Pour des informations détaillées, consultez permettre localhost & m'exclure docs.

Exemple de code

        import React from 'react';
        import ReactDOM from 'react-dom/client';
        import { MetricalpReactProvider } from '@metricalp/react';
        import './index.css';
        import { App } from './App.tsx';
        
        ReactDOM.createRoot(document.getElementById('root')!).render(
          <React.StrictMode>
            <MetricalpReactProvider allowLocalhost tid="YOUR_TID">
              <App />
            </MetricalpReactProvider>
          </React.StrictMode>
        );

UTILISATION

Si vous avez intégré la bibliothèque avec votre application, elle commencera automatiquement à suivre les événements screen_view. Metricalp écoute les changements de window.history et crée un événement screen_view à chaque changement de chemin par défaut. Donc, si vous souhaitez suivre uniquement les vues d'écran, votre application est prête juste après l'intégration. Vous n'avez rien d'autre à faire. Mais si vous souhaitez produire des événements personnalisés ou désactiver le suivi automatique des routes et créer des événements screen_view manuellement, suivez cette section.

Production d'Événements

Vous avez deux options pour produire des événements Metricalp avec cette bibliothèque. Un hook ou un appel direct de fonction.

Production d'événements avec Hook

        import { useMetricalp } from '@metricalp/react';

        export default function MyComponent() {
          // Appelez le hook pour obtenir la fonction d'événement metricalp
          const metricalpEvent = useMetricalp();
        
          return (
            <div>
              <button
                onClick={() => {
                  metricalpEvent({ type: 'click_test_button', custom_prop1: 'hook' });
                }}>
                Click me
              </button>
            </div>
          );
        }

Production d'événements avec appel direct de fonction

Parfois (en dehors des composants), vous ne pouvez pas appeler de hooks dans React. Vous pouvez donc importer la fonction de déclenchement d'événements directe de Metricalp.

        import { metricalpEvent } from "@metricalp/react";

        export default function MyComponent() {
        
          return (
            <div>
              <button
                onClick={() => {
                  metricalpEvent({ type: 'click_test_button', custom_prop1: 'direct' });
                }}
              >
                Click me
              </button>
            </div>
          );
        }

C'est entièrement à vous de préférer l'appel de hook ou de fonction directe dans toute votre application. Vous pouvez décider d'utiliser un seul ou les deux en fonction du lieu d'utilisation. Dans les exemples ci-dessus, nous produisons des événements personnalisés avec des propriétés personnalisées. Dans votre tableau de bord Metricalp, vous pouvez définir des alias pour custom_prop, puis vous pouvez utiliser directement cette clé dans les événements. Comme: metricalpEvent({ type: 'click_test_button', user_role: 'admin' }); ici, nous avons défini user_role comme alias de custom_prop1 dans les Paramètres du Tracker et maintenant nous le produisons directement dans les événements.

Personnaliser les comportements avec les Props

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