Integración con NextJS
No hay duda de que React y NextJS son algunos de los frameworks frontend más famosos hoy en día. Como Metricalp, estamos felices de tener una biblioteca de integración oficial para React y NextJS. Si usas React puro, consulta la documentación de integración de React. Si estás usando NextJS, estás en el lugar correcto. ¡Empecemos!
Nuestra biblioteca de integración está en NPM, su nombre es @metricalp/react
Instalación
Puedes instalarlo como:
yarn add @metricalp/react
o
npm install @metricalp/react
Integración
En el nivel superior de tu aplicación src/app/layout.tsx(NextJS App Router) | pages/_app.tsx(NextJS Pages Router) | App.js, envuelve tu aplicación con MetricalpReactProvider. Si estás usando NextJS 13 App Router, no necesitas añadir 'use client' porque esta biblioteca ya lo tiene internamente 🫡
Luego, proporciona tu tid (también conocido como TrackerID) como prop al proveedor. Básicamente esto es todo, Metricalp comenzará a recopilar automáticamente todos los eventos de visita y los cambios de ruta. Pero puedes personalizar comportamientos con props. Explicaremos todo.
Ejemplo de Integración de NextJS App Router
En src/app/layout.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 por defecto 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 la documentación de allow localhost & exclude me.
import type { Metadata } from 'next';
import { MetricalpReactProvider } from '@metricalp/react';
import { Inter } from 'next/font/google';
import './globals.css';
const inter = Inter({ subsets: ['latin'] });
export const metadata: Metadata = {
title: 'Create Next App',
description: 'Generated by create next app',
};
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html lang="es">
<body className={inter.className}>
<MetricalpReactProvider allowLocalhost tid="YOUR_TID">
{children}
</MetricalpReactProvider>
</body>
</html>
);
}Ejemplo de Integración de NextJS Pages Router
En src/pages/_app.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 por defecto 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 la documentación de allow localhost & exclude me.
import '@/styles/globals.css';
import type { AppProps } from 'next/app';
import { MetricalpReactProvider } from '@metricalp/react';
export default function App({ Component, pageProps }: AppProps) {
return (
<MetricalpReactProvider allowLocalhost tid="YOUR_TID">
<Component {...pageProps} />
</MetricalpReactProvider>
);
}USO
Si integraste la biblioteca con tu aplicación, comienza a rastrear automáticamente eventos de screen_view. Metricalp escucha los cambios en window.history y crea un evento screen_view en cada cambio de ruta de manera predeterminada. Por lo tanto, si solo deseas rastrear 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 desactivar el seguimiento 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() {
// Llama al hook para obtener la función de eventos de Metricalp
const metricalpEvent = useMetricalp();
return (
<div>
<button
onClick={() => {
metricalpEvent({ type: 'click_test_button', custom_prop1: 'hook' });
}}>
Haga clic en mí
</button>
</div>
);
}Producción de Eventos con Llamada Directa a Función
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 desde Metricalp.
import { metricalpEvent } from "@metricalp/react";
export default function MyComponent() {
return (
<div>
<button
onClick={() => {
metricalpEvent({ type: 'click_test_button', custom_prop1: 'direct' });
}}
>
Haga clic en mí
</button>
</div>
);
}Depende totalmente de ti si prefieres usar el hook o la llamada de función directa en toda tu aplicación. Puedes decidir sobre el uso de solo uno o puedes usar ambos dependiendo del lugar de uso. En los ejemplos anteriores producimos eventos personalizados con propiedades personalizadas. En tu panel de Metricalp puedes establecer alias de propiedades personalizadas, 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
tid
Este es tu tid, también conocido como tracker id. Puedes obtener información sobre cómo conseguirlo en Configuración del Tracker / Embed & Share. Necesitas proporcionar este atributo para que Metricalp funcione.
allowLocalhost
Si estás integrando Metricalp en tu localhost con fines de prueba, puedes establecer este atributo en "true". De lo contrario, Metricalp no recopilará eventos en localhost para ahorrar tu cuota de uso. Consulta esta documentación para obtener información detallada Si estás permitiendo nombres de host específicos en la configuración de tu tracker, agrega también localhost a los nombres de host permitidos.
customScriptUrl
Si has proxiado el archivo de script de eventos de Metricalp para evitar bloqueadores de anuncios, usa este atributo para proporcionar la URL del script proxy. Consulta esta documentación para obtener información detallada.
customEventEndpoint
Si has proxiado el endpoint de eventos de Metricalp para evitar bloqueadores de anuncios, usa este atributo para proporcionar el endpoint proxy. Consulta esta documentación para obtener información detallada.
disableAutoRouteCatch
Por defecto, Metricalp escucha eventos de window.history para detectar cambios de ruta en aplicaciones JS. Puedes deshabilitarlo configurando este atributo a true, y luego podrás rastrear rutas manualmente.
hashRouting
Si tu aplicación utiliza enrutamiento con hash (example.com/#about, example.com/#homepage), puedes configurar este atributo a true. Entonces, Metricalp escuchará cambios de ruta con hash.
allowCustomElmEvents
Metricalp admite de forma predeterminada el seguimiento de eventos personalizados basados en atributos HTML. Como <button data-metricalp-event="follow click" data-metricalp-user="John">Click</button>, este clic en el botón creará un evento personalizado con el nombre "follow click" y la propiedad personalizada "user" con el valor "John". Puedes desactivar esta función configurando este atributo a false. En la biblioteca está desactivado de forma predeterminada mientras la recolección de eventos personalizados con API es más robusta, como se describe anteriormente. Consulta esta documentación para obtener información detallada
initialSharedCustomProps
Si deseas adjuntar algunas propiedades personalizadas automáticamente y de forma predeterminada para todos o algunos eventos específicos, entonces puedes usar la propiedad initialSharedCustomProps.
<MetricalpReactProvider
allowLocalhost
tid="mam123456"
initialSharedCustomProps={{
_global: { custom_prop3: "v1.0" },
screen_view: { color: 'red', custom_prop2: 'Test' }
}}>_global es una clave especial para adjuntar algunas propiedades a todos los eventos. Ten en cuenta que, si estás adjuntando una propiedad personalizada a través de un alias, entonces ese alias debe estar definido para los eventos objetivo en la Configuración del Tracker; de lo contrario, será ignorado para ese evento. Puedes usar custom_prop1 como sintaxis para cualquier evento siempre.
Si deseas actualizar sharedCustomProps después de la configuración inicial para un tipo de evento específico, puedes usar el método exportado `updateSharedCustomPropsForType` como: updateSharedCustomPropsForType('screen_view', { color: 'red' }). Además, si deseas restablecer todo el objeto sharedCustomProps a un nuevo objeto, puedes usar el método exportado `resetSharedCustomProps` como: resetSharedCustomProps({ _global: { custom_prop3: 'v1.7' }, screen_view: { color: 'blue' } }). Consulta esta documentación para obtener información detallada.