Integration mit NextJS
Es besteht kein Zweifel, dass React und NextJS heutzutage zu den bekanntesten Frontend-Frameworks gehören. Als Metricalp sind wir glücklich, eine offizielle Integrationsbibliothek für React und NextJS zu haben. Wenn Sie reines React verwenden, schauen Sie bitte in die React Integrationsdokumentation. Wenn Sie NextJS verwenden, sind Sie am richtigen Ort. Lassen Sie uns anfangen!
Unsere Integrationsbibliothek befindet sich in NPM, ihr Name ist @metricalp/react
Installation
Sie können es so installieren:
yarn add @metricalp/react
oder
npm install @metricalp/react
Integration
In der obersten Ebene Ihrer App src/app/layout.tsx(NextJS App Router) | pages/_app.tsx(NextJS Pages Router) | App.js, wickeln Sie Ihre App mit MetricalpReactProvider ein. Wenn Sie den NextJS 13 App Router verwenden, müssen Sie 'use client' nicht hinzufügen, da diese Bibliothek dies bereits unter der Haube hat 🫡
Geben Sie dann Ihre tid (auch bekannt als TrackerID) als Prop an den Provider. Grundsätzlich ist dies alles, Metricalp beginnt automatisch, alle Besuchsereignisse und Routenänderungen zu sammeln. Sie können jedoch das Verhalten mit Props anpassen. Wir werden alles erklären.
NextJS App Router Integrationsbeispiel
In src/app/layout.tsx Bibliothek importieren import { MetricalpReactProvider } from '@metricalp/react';. Wickeln Sie dann Ihre App ein mit <MetricalpReactProvider allowLocalhost tid="YOUR_TID">
VERGESSEN SIE NICHT das tid Prop durch Ihre tid zu ersetzen.
Wir haben allowLocalhost hinzugefügt, weil Metricalp standardmäßig nicht in localhost funktioniert, um Ihre Kontingentgrenzen zu schützen. Wir haben localhost zu Testzwecken zugelassen. Sie möchten es nach dem einmaligen Testen entfernen, um Ihr Kontingent zu sparen. Weitere Informationen finden Sie unter allow localhost & exclude me Dokumentation.
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="de">
<body className={inter.className}>
<MetricalpReactProvider allowLocalhost tid="YOUR_TID">
{children}
</MetricalpReactProvider>
</body>
</html>
);
}NextJS Pages Router Integrationsbeispiel
In src/pages/_app.tsx Bibliothek importieren import { MetricalpReactProvider } from '@metricalp/react';. Wickeln Sie dann Ihre App ein mit <MetricalpReactProvider allowLocalhost tid="YOUR_TID">
VERGESSEN SIE NICHT das tid Prop durch Ihre tid zu ersetzen.
Wir haben allowLocalhost hinzugefügt, weil Metricalp standardmäßig nicht in localhost funktioniert, um Ihre Kontingentgrenzen zu schützen. Wir haben localhost zu Testzwecken zugelassen. Sie möchten es nach dem einmaligen Testen entfernen, um Ihr Kontingent zu sparen. Weitere Informationen finden Sie unter allow localhost & exclude me Dokumentation.
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>
);
}NUTZUNG
Wenn Sie die Bibliothek mit Ihrer App integriert haben, beginnt sie automatisch mit der Verfolgung von screen_view Ereignissen. Metricalp hört auf window.history Änderungen und erstellt standardmäßig ein screen_view Ereignis bei jedem Pfadwechsel. Wenn Sie also nur Bildschirmansichten verfolgen möchten, ist Ihre App nach der Integration bereit. Sie müssen nichts weiter tun. Wenn Sie jedoch benutzerdefinierte Ereignisse erstellen oder das automatische Routen-Tracking deaktivieren möchten und Sie screen_view Ereignisse manuell erstellen möchten, folgen Sie diesem Abschnitt.
Ereignisse produzieren
Sie haben zwei Möglichkeiten, Metricalp Ereignisse mit dieser Bibliothek zu erzeugen: einen Hook oder einen direkten Funktionsaufruf.
Ereignis produzieren mit Hook
import { useMetricalp } from '@metricalp/react';
export default function MyComponent() {
// Rufen Sie den Hook auf, um die Metricalp Ereignisfunktion zu erhalten
const metricalpEvent = useMetricalp();
return (
<div>
<button
onClick={() => {
metricalpEvent({ type: 'click_test_button', custom_prop1: 'hook' });
}}>
Klicken Sie mich
</button>
</div>
);
}Ereignis produzieren mit direktem Funktionsaufruf
Manchmal (außerhalb von Komponenten) können Sie keine Hooks in React aufrufen. Dann können Sie die direkte Ereignisauslösefunktion aus Metricalp importieren.
import { metricalpEvent } from "@metricalp/react";
export default function MyComponent() {
return (
<div>
<button
onClick={() => {
metricalpEvent({ type: 'click_test_button', custom_prop1: 'direct' });
}}
>
Klicken Sie mich
</button>
</div>
);
}Es liegt ganz bei Ihnen, ob Sie in Ihrer gesamten App einen Hook oder einen direkten Funktionsaufruf bevorzugen. Sie können sich für die Verwendung nur einer Option entscheiden oder beide je nach Verwendungsort verwenden. In den obigen Beispielen erzeugen wir benutzerdefinierte Ereignisse mit benutzerdefinierten Eigenschaften. In Ihrem Metricalp Dashboard können Sie benutzerdefinierte Attribut-Aliase festlegen, dann können Sie direkt diesen Schlüssel in Ereignissen verwenden. Wie: metricalpEvent({ type: 'click_test_button', user_role: 'admin' }); hier haben wir user_role als Alias von custom_prop1 in den Tracker-Einstellungen definiert und jetzt erzeugen wir ihn direkt in Ereignissen.
Verhalten mit Props anpassen
tid
Dies ist Ihre tid, auch bekannt als Tracker-ID. Sie können Informationen darüber erhalten, wie Sie diese erhalten unter Tracker Einstellungen / Embed & Share. Sie müssen dieses Attribut angeben, damit Metricalp funktioniert.
allowLocalhost
Wenn Sie Metricalp zu Testzwecken in Ihrem localhost integrieren, können Sie dieses Attribut auf "true" setzen. Andernfalls sammelt Metricalp keine Ereignisse im localhost, um Ihr Nutzungskontingent zu sparen. Weitere Informationen finden Sie in dieser Dokumentation Wenn Sie in Ihren Tracker-Einstellungen bestimmte Hostnamen zulassen, fügen Sie auch localhost zu den erlaubten Hostnamen hinzu.
customScriptUrl
Wenn Sie die Metricalp Event-Skriptdatei proxyen, um Werbeblocker zu verhindern, verwenden Sie dieses Attribut, um die proxy URL des Skripts anzugeben. Weitere Informationen finden Sie in dieser Dokumentation.
customEventEndpoint
Wenn Sie den Metricalp Event-Endpunkt proxyen, um Werbeblocker zu verhindern, verwenden Sie dieses Attribut, um den proxy Endpunkt anzugeben. Weitere Informationen finden Sie in dieser Dokumentation.
disableAutoRouteCatch
Standardmäßig lauscht Metricalp auf window.history Ereignisse, um Routenänderungen in JS-Anwendungen zu erfassen. Sie können dies deaktivieren, indem Sie dieses Attribut auf true setzen, dann können Sie Routen manuell verfolgen.
hashRouting
Wenn Ihre Anwendung Hash-Routing verwendet (example.com/#about, example.com/#homepage), können Sie dieses Attribut auf true setzen. Dann wird Metricalp auf Hash-Routenänderungen lauschen.
allowCustomElmEvents
Metricalp unterstützt standardmäßig HTML-Attribut-basierte benutzerdefinierte Ereignisverfolgung. Zum Beispiel <button data-metricalp-event="follow click" data-metricalp-user="John">Click</button>, dieser Button-Click erzeugt ein benutzerdefiniertes Ereignis mit dem Namen "follow click" und dem benutzerdefinierten Attribut "user" mit dem Wert "John". Sie können diese Funktion deaktivieren, indem Sie dieses Attribut auf false setzen. In der Bibliothek ist es standardmäßig deaktiviert, während die Sammlung benutzerdefinierter Ereignisse mit der API robuster ist, wie oben beschrieben. Weitere Informationen finden Sie in dieser Dokumentation
initialSharedCustomProps
Wenn Sie möchten, dass einige benutzerdefinierte Attribute automatisch und standardmäßig für alle oder bestimmte Ereignisse angehängt werden, können Sie die Eigenschaft initialSharedCustomProps verwenden.
<MetricalpReactProvider
allowLocalhost
tid="mam123456"
initialSharedCustomProps={{
_global: { custom_prop3: "v1.0" },
screen_view: { color: 'red', custom_prop2: 'Test' }
}}>_global ist ein spezieller Schlüssel zum Anhängen von Attributen an alle Ereignisse. Beachten Sie, dass, wenn Sie ein benutzerdefiniertes Attribut über Alias anhängen, dieser Alias für die Zielereignisse in den Tracker-Einstellungen definiert sein sollte, sonst wird er für dieses Ereignis ignoriert. Sie können immer custom_prop1 ähnliche Syntax für jedes Ereignis verwenden.
Wenn Sie sharedCustomProps nach der ersten Einrichtung für ein bestimmtes Ereignistyp aktualisieren möchten, können Sie die exportierte Methode `updateSharedCustomPropsForType` wie folgt verwenden: updateSharedCustomPropsForType('screen_view', { color: 'red' }). Außerdem, wenn Sie das gesamte sharedCustomProps-Objekt auf ein neues Objekt zurücksetzen möchten, können Sie die exportierte Methode `resetSharedCustomProps` wie folgt verwenden: resetSharedCustomProps({ _global: { custom_prop3: 'v1.7' }, screen_view: { color: 'blue' } }). Weitere Informationen finden Sie in dieser Dokumentation.