Intégration avec NextJS
Il ne fait aucun doute que React et NextJS sont parmi les frameworks frontend les plus célèbres de nos jours. En tant que Metricalp, nous sommes heureux d'avoir une bibliothèque d'intégration officielle pour React et NextJS. Si vous utilisez React pur, consultez la documentation d'intégration de React. Si vous utilisez NextJS, vous êtes au bon endroit. Commençons !
Notre bibliothèque d'intégration est sur NPM, son nom est @metricalp/react
Installation
Vous pouvez 'installer comme suit :
yarn add @metricalp/react
ou
npm install @metricalp/react
Intégration
Dans le niveau supérieur de votre application src/app/layout.tsx(NextJS App Router) | pages/_app.tsx(NextJS Pages Router) | App.js, enveloppez votre application avec MetricalpReactProvider. Si vous utilisez NextJS 13 App Router, vous n'avez pas besoin d'ajouter 'use client' car cette bibliothèque 'a déjà sous le capot 🫡
Ensuite, donnez votre tid (également connu sous le nom de TrackerID) comme prop au provider. Fondamentalement, c'est tout, Metricalp commencera automatiquement à collecter tous les événements de visite et les changements de route. Mais vous pouvez personnaliser les comportements avec des props. Nous allons tout expliquer.
Exemple d'Intégration de NextJS App Router
Dans src/app/layout.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 car par défaut Metricalp ne fonctionne pas sur localhost pour protéger vos limites de quota. Nous avons autorisé localhost à des fins de test. Vous voudrez le supprimer après 'avoir testé une fois pour économiser votre quota. Pour des informations détaillées, consultez la documentation 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="fr">
<body className={inter.className}>
<MetricalpReactProvider allowLocalhost tid="YOUR_TID">
{children}
</MetricalpReactProvider>
</body>
</html>
);
}Exemple d'Intégration de NextJS Pages Router
Dans src/pages/_app.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 car par défaut Metricalp ne fonctionne pas sur localhost pour protéger vos limites de quota. Nous avons autorisé localhost à des fins de test. Vous voudrez le supprimer après 'avoir testé une fois pour économiser votre quota. Pour des informations détaillées, consultez la documentation 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>
);
}UTILISATION
Si vous avez intégré la bibliothèque avec votre application, elle commence automatiquement à suivre les événements de screen_view. Metricalp écoute les changements de window.history et crée un événement screen_view à chaque changement de route par défaut. Donc, si vous souhaitez ne suivre que les vues d'écran, votre application est prête juste après '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.
Produire des Événements
Vous avez deux options pour produire des événements Metricalp avec cette bibliothèque : un hook ou un appel de fonction direct.
Production d'Événements avec Hook
import { useMetricalp } from '@metricalp/react';
export default function MyComponent() {
// Appelez le hook pour obtenir la fonction d'événements Metricalp
const metricalpEvent = useMetricalp();
return (
<div>
<button
onClick={() => {
metricalpEvent({ type: 'click_test_button', custom_prop1: 'hook' });
}}>
Cliquez sur moi
</button>
</div>
);
}Production d'Événements avec Appel Direct de Fonction
Parfois (en dehors des composants), vous ne pouvez pas appeler de hooks en React. Vous pouvez donc importer la fonction de déclenchement d'événement directe depuis Metricalp.
import { metricalpEvent } from "@metricalp/react";
export default function MyComponent() {
return (
<div>
<button
onClick={() => {
metricalpEvent({ type: 'click_test_button', custom_prop1: 'direct' });
}}
>
Cliquez sur moi
</button>
</div>
);
}Il vous appartient totalement de préférer le hook ou 'appel de fonction direct dans toute votre application. Vous pouvez décider d'utiliser uniquement 'un ou 'autre ou les deux en fonction de 'endroit où ils sont utilisés. 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 de propriétés personnalisées, 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 Props
tid
Ceci est votre tid, également appelé tracker id. Vous pouvez obtenir des informations sur comment 'obtenir depuis Paramètres du Tracker / Embed & Share. Vous devez fournir cet attribut pour que Metricalp fonctionne.
allowLocalhost
Si vous intégrez Metricalp dans votre localhost à des fins de test, vous pouvez définir cet attribut sur "true". Sinon, Metricalp ne collectera pas les événements sur localhost pour économiser votre quota d'utilisation. Consultez cette documentation pour des informations détaillées Si vous autorisez des noms d'hôte spécifiques dans les paramètres de votre tracker, ajoutez également localhost aux noms d'hôte autorisés.
customScriptUrl
Si vous avez proxyé le fichier de script d'événements de Metricalp pour éviter les bloqueurs de publicité, utilisez cet attribut pour fournir 'URL du script proxy. Consultez cette documentation pour des informations détaillées.
customEventEndpoint
Si vous avez proxyé 'endpoint des événements de Metricalp pour éviter les bloqueurs de publicité, utilisez cet attribut pour fournir 'endpoint proxy. Consultez cette documentation pour des informations détaillées.
disableAutoRouteCatch
Par défaut, Metricalp écoute les événements window.history pour détecter les changements de route dans les applications JS. Vous pouvez le désactiver en définissant cet attribut sur true, puis vous pourrez suivre les routes manuellement.
hashRouting
Si votre application utilise le routage par hachage (example.com/#about, example.com/#homepage), vous pouvez définir cet attribut sur true. Ensuite, Metricalp écoutera les changements de route par hachage.
allowCustomElmEvents
Metricalp prend en charge par défaut le suivi des événements personnalisés basés sur les attributs HTML. Comme <button data-metricalp-event="follow click" data-metricalp-user="John">Click</button>, ce clic sur le bouton créera un événement personnalisé avec le nom "follow click" et la propriété personnalisée "user" avec la valeur "John". Vous pouvez désactiver cette fonctionnalité en définissant cet attribut sur false. Dans la bibliothèque, il est désactivé par défaut, tandis que la collecte d'événements personnalisés avec 'API est plus robuste, comme décrit ci-dessus. Consultez cette documentation pour des informations détaillées
initialSharedCustomProps
Si vous souhaitez attacher certaines propriétés personnalisées automatiquement et par défaut pour tous ou certains événements spécifiques, vous pouvez utiliser la propriété initialSharedCustomProps.
<MetricalpReactProvider
allowLocalhost
tid="mam123456"
initialSharedCustomProps={{
_global: { custom_prop3: "v1.0" },
screen_view: { color: 'red', custom_prop2: 'Test' }
}}>_global est une clé spéciale pour attacher certaines propriétés à tous les événements. Gardez à 'esprit que, si vous attachez une propriété personnalisée via un alias, cet alias doit être défini pour les événements cibles dans les Paramètres du Tracker, sinon il sera ignoré pour cet événement. Vous pouvez utiliser la syntaxe custom_prop1 comme pour n'importe quel événement.
Si vous souhaitez mettre à jour sharedCustomProps après la configuration initiale pour un type d'événement spécifique, vous pouvez utiliser la méthode exportée `updateSharedCustomPropsForType` comme : updateSharedCustomPropsForType('screen_view', { color: 'red' }). De plus, si vous souhaitez réinitialiser 'objet sharedCustomProps entier à un nouvel objet, vous pouvez utiliser la méthode exportée `resetSharedCustomProps` comme : resetSharedCustomProps({ _global: { custom_prop3: 'v1.7' }, screen_view: { color: 'blue' } }). Consultez cette documentation pour des informations détaillées.