Integración con React

Sin duda, React es uno de los frameworks frontend más famosos hoy en día. En Metricalp, estamos felices de tener una biblioteca de integración oficial para React y NextJS. Si estás usando NextJS, consulta la documentación de integración de NextJS. Si estás usando React, estás en el lugar correcto. ¡Vamos a empezar!

Nuestra biblioteca de integración en NPM se llama @metricalp/react

Instalación

Puedes instalarlo así:

yarn add @metricalp/react

o

npm install @metricalp/react

Integración

En el nivel superior de tu aplicación en src/index.js | src/main.tsx(Vite) | App.js, envuelve tu aplicación con MetricalpReactProvider. Luego, proporciona tu tid (alias TrackerID) como prop al proveedor. Básicamente, eso es todo, Metricalp comenzará a recopilar todos los eventos de visita y cambio de ruta automáticamente. Pero puedes personalizar los comportamientos con props. Explicaremos todo.

Ejemplo (proyecto React creado con Vite)

En src/main.tsx importa la biblioteca import { MetricalpReactProvider } from '@metricalp/react';. Luego envuelve tu aplicación con <MetricalpReactProvider allowLocalhost tid="YOUR_TID">

NO OLVIDES reemplazar el prop tid con tu tid.

Añadimos allowLocalhost porque, de forma predeterminada, Metricalp no funciona en localhost para proteger los límites de tu cuota. Permitimos localhost con fines de prueba. Querrás eliminarlo después de probarlo una vez para ahorrar tu cuota. Para información detallada, consulta permitir localhost & excluirme docs.

Ejemplo de código

        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

Si has integrado la biblioteca con tu aplicación, comenzará automáticamente a rastrear eventos screen_view. Metricalp escucha los cambios de window.history y crea un evento screen_view en cada cambio de ruta de forma predeterminada. Por lo tanto, si deseas rastrear solo vistas de pantalla, tu aplicación estará lista justo después de la integración. No necesitas hacer nada extra. Pero si deseas producir eventos personalizados o deshabilitar el rastreo automático de rutas y crear eventos screen_view manualmente, sigue esta sección.

Producir Eventos

Tienes dos opciones para producir eventos Metricalp con esta biblioteca. Un hook o una llamada de función directa.

Producción de eventos con Hook

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

        export default function MyComponent() {
          // Llamar al hook para obtener la función de evento de metricalp
          const metricalpEvent = useMetricalp();
        
          return (
            <div>
              <button
                onClick={() => {
                  metricalpEvent({ type: 'click_test_button', custom_prop1: 'hook' });
                }}>
                Click me
              </button>
            </div>
          );
        }

Producción de eventos con llamada de función directa

A veces (fuera de los componentes) no puedes llamar a hooks en React. Entonces, puedes importar la función de activación de eventos directa 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>
          );
        }

Depende totalmente de ti si prefieres el hook o la llamada de función directa en toda tu aplicación. Puedes decidir usar solo uno o ambos según el lugar de uso. En los ejemplos anteriores, producimos eventos personalizados con propiedades personalizadas. En tu panel de control de Metricalp puedes configurar alias de custom_prop, luego puedes usar directamente esa clave en los eventos. Como: metricalpEvent({ type: 'click_test_button', user_role: 'admin' }); aquí definimos user_role como alias de custom_prop1 en la Configuración del Tracker y ahora lo estamos produciendo directamente en los eventos.

Personalizar comportamientos con Props

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