Integration mit Purem(Vanilla) JavaScript

In diesem Abschnitt erklären wir Ihnen, wie Sie Ihre Website integrieren können, indem Sie das Metricalp-Skript in Ihre Website einbetten. Alle anderen Integrationsbibliotheken verwenden diese Methode unter der Haube.

Zuerst benötigen Sie Ihre tid (auch bekannt als Tracker ID). Sie können es von Tracker-Einstellungen / Einbetten & Teilen Bildschirm erhalten.

Nachdem Sie Ihre tid erhalten haben, sind Sie bereit, das Metricalp-Skript in Ihre Website einzubetten. Sie müssen den folgenden Codeausschnitt oben auf jeder Seite platzieren. Bitte vergessen Sie nicht, YOUR_TID durch Ihre tid zu ersetzen.

<script src="https://cdn.metricalp.com/event/metricalp.js" data-allow-localhost="true" data-tid="YOUR_TID" defer></script>

Das war's. Metricalp beginnt automatisch, Ereignisse von Ihrer Website zu sammeln, nachdem diese eine Zeile hinzugefügt wurde. Wie toll ist das, oder? 🫡

Tauchen wir nun in die Details ein. Das obige Skript hat das `defer`-Attribut, was bedeutet, dass das Skript das Laden der Seite nicht blockiert, aber die Skriptausführung wird vor allen anderen Skriptausführungen auf der Seite stattfinden, die nach diesem Skript kommen. Wenn Sie das Skript jedoch asynchron laden möchten, können Sie das `defer`-Attribut entfernen und es durch das `async`-Attribut ersetzen. In diesem Fall wird das Skript asynchron geladen, aber es kann ein Problem sein, wenn Sie ein Ereignis direkt nach dem Seitenladen auslösen möchten, da das Skript möglicherweise nicht vollständig geladen ist, bevor Sie das Ereignis auslösen. Um dies zu lösen und den gesamten Prozess flüssiger zu gestalten, können wir eine Zeile mehr direkt über unserem Skript hinzufügen:

<script>window.metricalp = window.metricalp || {queue: [], event: function(e){this.queue.push(e)}}</script>
<script src="https://cdn.metricalp.com/event/metricalp.js" data-allow-localhost="true" data-tid="YOUR_TID" async></script>

Jetzt haben wir defer mit async ersetzt und eine Zeile mehr direkt über unsere Skriptzeile hinzugefügt. Wir garantieren, dass jedes Ereignis unabhängig von der Ladezeit unseres Hauptskripts in die Warteschlange gestellt wird. Weil wir jetzt unsere Ereignisse in einer Warteschlange sammeln, bis unser Skript geladen ist, und dann alle Ereignisse in der Warteschlange feuert. So können Sie Ereignisse direkt nach dem Laden einer Seite auslösen. Wir empfehlen im Allgemeinen dieses zweite Code-Snippet (wir verwenden dies in unseren Integrationsbibliotheken), da es leistungsfähiger, sicherer und leichter für das Seitenladen ist.

Während wir das data-tid Attribut bereitstellen, haben wir ein weiteres Datenattribut data-allow-localhost="true" bereitgestellt, weil Metricalp standardmäßig niemals Ereignisse von localhost (127.0.0.1) sammelt, um Ihre Nutzungskontingente zu schonen. Wenn Sie jedoch zum ersten Mal integrieren, können Sie localhost-Ereignisse zu Testzwecken zulassen. Nachdem Sie Ihre Integration abgeschlossen haben, können Sie dieses Attribut entfernen, bevor Sie Ihre Website in die Produktion veröffentlichen. Weitere Informationen finden Sie in den allow localhost & exclude me docs

Es gibt noch ein paar weitere Optionen, um das Verhalten des Metricalp-Skripts anzupassen, alle können in der API-Referenz gefunden werden.

Standardmäßig beginnt Metricalp automatisch mit dem Sammeln von screen_view Ereignissen (dies kann mit der Option data-disable-auto-route-catch deaktiviert werden, bitte überprüfen Sie die API-Referenz für Details). Wenn Sie jedoch ein Ereignis manuell auslösen möchten (screen_view oder ein benutzerdefiniertes Ereignis), können Sie die Funktion window.metricalp.event oder benutzerdefinierte Datenattribute verwenden. Sie erfahren mehr darüber in der Custom Event & Props. Wenn Sie benutzerdefinierte Ereignisse auslösen, sollte Ihr Skript geladen sein, bevor Sie das Ereignis auslösen. In beiden oben genannten Codeausschnitten ist dies in der Regel der Fall. Im ersten Szenario kann es jedoch vorkommen, dass das Ereignis ausgelöst wird, bevor das defer-Skript aufgerufen wird, was ein Problem sein könnte. Dies ist zwar ein sehr seltener Randfall, aber Sie können das zweite Code-Snippet verwenden, um sicher zu sein.

Manchmal möchten Sie möglicherweise einige benutzerdefinierte Eigenschaften automatisch an einige (oder alle) Ereignisse anhängen. Dies kann mit dem zweiten Ansatz eingestellt werden, und definieren Sie diese automatisch angehängten Eigenschaften im sharedCustomProps Objekt wie folgt:

<script>
      window.metricalp = window.metricalp || {
          queue: [],
          sharedCustomProps: {
            _global: { custom_prop1: "Test1" },
            screen_view: {
              logged_in: 'not_logged_in',
              custom_prop2: "Test2",
            }
          },
          event: function(e){this.queue.push(e)}
      }
</script>
<script src="https://cdn.metricalp.com/event/metricalp.js" data-allow-localhost="true" data-tid="YOUR_TID" async></script>

_global ist ein spezieller Schlüssel zum Anhängen von Eigenschaften an alle Ereignisse. Beachten Sie, dass, wenn Sie eine benutzerdefinierte Eigenschaft über einen Alias anhängen, dieser Alias für die Zielereignisse in den Tracker-Einstellungen definiert sein muss, andernfalls wird er für dieses Ereignis ignoriert. Sie können immer die Syntax custom_prop1 für jedes Ereignis verwenden. Weitere detaillierte Informationen zu sharedCustomProps finden Sie im Abschnitt Custom Event & Props. Wenn Sie die React-Bibliothek verwenden, um Metricalp in React / NextJS zu integrieren, können Sie die React und NextJS Dokumentationen lesen, um zu erfahren, wie Sie sharedCustomProps in Ihrer React / NextJS App einstellen können.