Integrazione con NextJS
Non c'è dubbio che React e NextJS siano tra i framework frontend più famosi al giorno d'oggi. Come Metricalp, siamo felici di avere una libreria di integrazione ufficiale per React e NextJS. Se stai utilizzando React puro, consulta la documentazione di integrazione di React. Se stai utilizzando NextJS, sei nel posto giusto. Iniziamo!
La nostra libreria di integrazione è su NPM, il suo nome è @metricalp/react
Installazione
Puoi installarlo come:
yarn add @metricalp/react
o
npm install @metricalp/react
Integrazione
Nel livello superiore della tua applicazione src/app/layout.tsx(NextJS App Router) | pages/_app.tsx(NextJS Pages Router) | App.js, avvolgi la tua app con MetricalpReactProvider. Se stai utilizzando NextJS 13 App Router, non è necessario aggiungere 'use client' perché questa libreria lo ha già sotto il cofano 🫡
Quindi, dai il tuo tid (anche noto come TrackerID) come prop al provider. Fondamentalmente, questo è tutto, Metricalp inizierà automaticamente a raccogliere tutti gli eventi di visita e i cambiamenti di percorso. Ma puoi personalizzare i comportamenti con i props. Spiegheremo tutto.
Esempio di Integrazione di NextJS App Router
In src/app/layout.tsx importa la libreria import { MetricalpReactProvider } from '@metricalp/react';. Quindi 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é per impostazione predefinita Metricalp non funziona in localhost per proteggere i tuoi limiti di quota. Abbiamo permesso localhost per scopi di test. Vorrai rimuoverlo dopo averlo testato una volta per risparmiare la tua quota. Per informazioni dettagliate consulta la documentazione di 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="it">
<body className={inter.className}>
<MetricalpReactProvider allowLocalhost tid="YOUR_TID">
{children}
</MetricalpReactProvider>
</body>
</html>
);
}Esempio di Integrazione di NextJS Pages Router
In src/pages/_app.tsx importa la libreria import { MetricalpReactProvider } from '@metricalp/react';. Quindi 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é per impostazione predefinita Metricalp non funziona in localhost per proteggere i tuoi limiti di quota. Abbiamo permesso localhost per scopi di test. Vorrai rimuoverlo dopo averlo testato una volta per risparmiare la tua quota. Per informazioni dettagliate consulta la documentazione di 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>
);
}UTILIZZO
Se hai integrato la libreria con la tua app, inizia automaticamente a tracciare gli eventi screen_view. Metricalp ascolta i cambiamenti di window.history e crea un evento screen_view su ogni cambio di percorso di default. Quindi, se vuoi tracciare solo le visualizzazioni 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.
Produrre Eventi
Hai due opzioni per produrre eventi Metricalp con questa libreria: un hook o una chiamata diretta alla funzione.
Produzione di Eventi con Hook
import { useMetricalp } from '@metricalp/react';
export default function MyComponent() {
// Chiama il hook per ottenere la funzione di eventi Metricalp
const metricalpEvent = useMetricalp();
return (
<div>
<button
onClick={() => {
metricalpEvent({ type: 'click_test_button', custom_prop1: 'hook' });
}}>
Clicca su di me
</button>
</div>
);
}Produzione di Eventi con Chiamata Diretta alla Funzione
A volte (al di fuori dei componenti) non puoi chiamare hook in React. Quindi puoi importare la funzione di attivazione dell'evento direttamente da Metricalp.
import { metricalpEvent } from "@metricalp/react";
export default function MyComponent() {
return (
<div>
<button
onClick={() => {
metricalpEvent({ type: 'click_test_button', custom_prop1: 'direct' });
}}
>
Clicca su di me
</button>
</div>
);
}Dipende completamente da te se preferisci l'uso del hook o della chiamata diretta alla funzione in tutta la tua app. Puoi decidere sull'uso di solo uno o puoi usare entrambi a seconda del luogo di utilizzo. Negli esempi precedenti produciamo eventi personalizzati con proprietà personalizzate. Nel tuo dashboard Metricalp puoi impostare alias di proprietà personalizzate, quindi puoi utilizzare 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 Comportamenti con Props
tid
Questo è il tuo tid, anche noto come tracker id. Puoi ottenere informazioni su come ottenerlo su Impostazioni Tracker / Embed & Share. Devi fornire questo attributo per far funzionare Metricalp.
allowLocalhost
Se stai integrando Metricalp nel tuo localhost per scopi di test, puoi impostare questo attributo su "true". Altrimenti, Metricalp non raccoglierà eventi in localhost per risparmiare la tua quota di utilizzo. Consulta questa documentazione per informazioni dettagliate Se stai consentendo nomi host specifici nelle impostazioni del tuo tracker, aggiungi anche localhost ai nomi host consentiti.
customScriptUrl
Se hai proxiato il file di script di eventi di Metricalp per prevenire i blocchi pubblicitari, utilizza questo attributo per fornire la URL del script proxy. Consulta questa documentazione per informazioni dettagliate.
customEventEndpoint
Se hai proxiato l'endpoint degli eventi di Metricalp per prevenire i blocchi pubblicitari, utilizza questo attributo per fornire l'endpoint proxy. Consulta questa documentazione per informazioni dettagliate.
disableAutoRouteCatch
Per impostazione predefinita, Metricalp ascolta gli eventi window.history per rilevare i cambi di percorso nelle applicazioni JS. Puoi disabilitarlo impostando questo attributo su true, quindi puoi tracciare le rotte manualmente.
hashRouting
Se la tua applicazione utilizza il routing hash (example.com/#about, example.com/#homepage), puoi impostare questo attributo su true. Allora Metricalp ascolterà i cambi di percorso con hash.
allowCustomElmEvents
Metricalp supporta di default il tracciamento di eventi personalizzati basati su attributi HTML. Come <button data-metricalp-event="follow click" data-metricalp-user="John">Click</button>, questo clic sul pulsante creerà un evento personalizzato con il nome "follow click" e la proprietà personalizzata "user" con il valore "John". Puoi disattivare questa funzionalità impostando questo attributo su false. Nella libreria è disattivato per default mentre la raccolta di eventi personalizzati con l'API è più robusta come descritto sopra. Consulta questa documentazione per informazioni dettagliate
initialSharedCustomProps
Se vuoi collegare alcune proprietà personalizzate automaticamente e di default per tutti o alcuni eventi specifici, allora puoi utilizzare la proprietà initialSharedCustomProps.
<MetricalpReactProvider
allowLocalhost
tid="mam123456"
initialSharedCustomProps={{
_global: { custom_prop3: "v1.0" },
screen_view: { color: 'red', custom_prop2: 'Test' }
}}>_global è una chiave speciale per collegare alcune proprietà a tutti gli eventi. Tieni presente che, se stai collegando una proprietà personalizzata tramite alias, allora quell'alias dovrebbe essere definito per gli eventi target nelle Impostazioni del Tracker, altrimenti sarà ignorato per quell'evento. Puoi usare sempre una sintassi come custom_prop1 per qualsiasi evento.
Se desideri aggiornare sharedCustomProps dopo la configurazione iniziale per un tipo di evento specifico, puoi utilizzare il metodo esportato `updateSharedCustomPropsForType` come: updateSharedCustomPropsForType('screen_view', { color: 'red' }). Inoltre, se vuoi resettare l'intero oggetto sharedCustomProps a un nuovo oggetto, puoi usare il metodo esportato `resetSharedCustomProps` come: resetSharedCustomProps({ _global: { custom_prop3: 'v1.7' }, screen_view: { color: 'blue' } }). Consulta questa documentazione per informazioni dettagliate.