Integrazione con React

Senza dubbio, React è uno dei framework frontend più famosi oggi. Come Metricalp, siamo felici di avere una libreria di integrazione ufficiale per React e NextJS. Se stai usando NextJS, consulta la documentazione di integrazione di NextJS. Se stai usando React, sei nel posto giusto. Iniziamo!

La nostra libreria di integrazione su NPM si chiama @metricalp/react

Installazione

Puoi installarlo come:

yarn add @metricalp/react

oppure

npm install @metricalp/react

Integrazione

Nel livello superiore della tua app in src/index.js | src/main.tsx(Vite) | App.js, avvolgi la tua app con MetricalpReactProvider. Quindi fornisci il tuo tid (alias TrackerID) come prop al provider. In pratica è tutto, Metricalp inizierà a raccogliere tutti gli eventi di visita e di cambio di rotta automaticamente. Ma puoi personalizzare i comportamenti con i props. Spiegheremo tutto.

Esempio (progetto React avviato con Vite)

In src/main.tsx importa la libreria import { MetricalpReactProvider } from '@metricalp/react';. Poi avvolgi la tua app con <MetricalpReactProvider allowLocalhost tid="YOUR_TID">

NON DIMENTICARE di sostituire il prop tid con il tuo tid.

Abbiamo aggiunto allowLocalhost perché, di default, Metricalp non funziona su localhost per proteggere i limiti della tua quota. Abbiamo permesso localhost per scopi di test. Vorrai rimuoverlo dopo aver testato una volta per risparmiare la tua quota. Per maggiori informazioni consulta permetti localhost & escludimi docs.

Esempio di codice

        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>
        );

USO

Se hai integrato la libreria con la tua app, inizierà automaticamente a tracciare gli eventi screen_view. Metricalp ascolta i cambiamenti di window.history e crea un evento screen_view ad ogni cambio di percorso di default. Quindi, se vuoi tracciare solo le viste delle schermate, la tua app è pronta subito dopo l'integrazione. Non devi fare nient'altro. Ma se vuoi produrre eventi personalizzati o disabilitare il tracciamento automatico delle rotte e creare manualmente eventi screen_view, segui questa sezione.

Produzione di Eventi

Hai due opzioni per produrre eventi Metricalp con questa libreria: un hook o una chiamata diretta di funzione.

Produzione di eventi con Hook

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

        export default function MyComponent() {
          // Chiama l'hook per ottenere la funzione dell'evento metricalp
          const metricalpEvent = useMetricalp();
        
          return (
            <div>
              <button
                onClick={() => {
                  metricalpEvent({ type: 'click_test_button', custom_prop1: 'hook' });
                }}>
                Click me
              </button>
            </div>
          );
        }

Produzione di eventi con chiamata diretta di funzione

A volte (fuori dai componenti) non puoi chiamare gli hook in React. Puoi quindi importare la funzione di trigger degli eventi diretta da 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>
          );
        }

È totalmente a tua discrezione preferire l'uso del hook o della chiamata diretta di funzione in tutta la tua app. Puoi decidere di usarne solo uno o entrambi a seconda del luogo di utilizzo. Negli esempi sopra produciamo eventi personalizzati con proprietà personalizzate. Nel tuo dashboard di Metricalp puoi impostare alias per custom_prop e quindi puoi usare direttamente quella chiave negli eventi. Come: metricalpEvent({ type: 'click_test_button', user_role: 'admin' }); qui abbiamo definito user_role come alias di custom_prop1 nelle Impostazioni del Tracker e ora lo stiamo producendo direttamente negli eventi.

Personalizzare i comportamenti con i Props

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