OneTrace.pro Hilfe

Website anbinden

Der Tracker ist ein kleines Skript auf den Seiten Ihrer Website. Er erfasst Seitenaufrufe, überträgt Kundenaktionen (Produktaufruf, Warenkorb, Bestellung, Anmeldung), zeigt Empfehlungs-Widgets an und meldet Besucher für Web Push an. Alles für die Anbindung finden Sie auf der Seite Website → Anbindung, Web Push richten Sie auf der Seite Website → Web Push ein.

Der Bereich steht allen Projektmitgliedern offen. Website-Domains und Widgets ändern können „Inhaber“, „Administrator“ und „Manager“. Einen Schlüssel für die Website erstellen können „Inhaber“ und „Administrator“.

Tracker installieren

Der Tab Installation umfasst drei Schritte.

1. Code für jede Seite

  1. Wählen Sie im Feld Schreibschlüssel einen Schlüssel. Gibt es noch keinen, klicken Sie auf Website-Schlüssel erstellen.
  2. Kopieren Sie den Code mit der Kopierschaltfläche.
  3. Fügen Sie ihn in den <head> aller Seiten Ihrer Website ein – meist in die gemeinsame Kopfzeilen-Vorlage.

Der Code sieht so aus (Adresse und Schlüssel sind im Bereich bereits eingesetzt):

<script>
!function(w,d,u){var c=w.cdp=w.cdp||[];if(c.version)return;['init','page','track','identify','alias','reset','setLanguage','widgets','renderRecommendations'].forEach(function(m){c[m]=c[m]||function(){c.push([m].concat([].slice.call(arguments)))}});var s=d.createElement('script');s.async=1;s.src=u;d.head.appendChild(s)}(window,document,'https://cdp.onetrace.pro/tracker/cdp.js');
cdp.init('cdp_wk_…', { host: 'https://cdp.onetrace.pro' });
cdp.page();
</script>

Das Skript wird asynchron geladen und verlangsamt die Website nicht. Aufrufe von cdp.track() können Sie direkt nach dem Code ausführen: Sie warten, bis der Tracker geladen ist. Jedem Browser weist der Tracker eine dauerhafte Besucherkennung zu (Cookie cdp_aid für ein Jahr) und speichert die UTM-Parameter des Besuchs.

Der Schreibschlüssel ist im Seitencode sichtbar – das ist in Ordnung: Er kann nur Ereignisse senden. Sind in der Liste keine Schlüssel verfügbar, wurden sie vor Einführung dieses Bereichs erstellt und können nicht vollständig angezeigt werden. Erstellen Sie einen neuen Website-Schlüssel oder übernehmen Sie den Schlüssel aus dem Code, der bereits auf der Website eingebunden ist.

Tab „Installation“: Tracker-Code und Installationsprüfung

2. Prüfung

Öffnen Sie nach der Installation eine beliebige Seite Ihrer Website. Nach einigen Sekunden erscheint im Block Prüfung eine Tabelle: Domain, Ereignisse in 7 Tagen und der Zeitpunkt des letzten Ereignisses. Solange keine Ereignisse vorliegen, zeigt der Bereich „Warten auf die ersten Ereignisse“. Die Prüfung aktualisiert sich alle 10 Sekunden selbst, solange der Bereich geöffnet ist.

3. Website-Domains

Damit keine fremde Website im Namen Ihres Projekts Ereignisse senden und Empfehlungen abrufen kann, geben Sie die Domains Ihrer Website an:

  1. Geben Sie eine Domain ein, zum Beispiel shop.example.com, und klicken Sie auf +. Eine Domain aus der Prüftabelle fügen Sie mit Zu Domains hinzufügen hinzu.
  2. Klicken Sie auf Speichern.

Eine Domain erlaubt auch ihre Subdomains: shop.ru lässt www.shop.ru zu. Solange die Liste leer ist, funktioniert der Schlüssel auf jeder Website („Keine Einschränkung“). Anfragen von Ihrem Server betrifft die Beschränkung nicht. Sie können bis zu 20 Domains angeben.

Single-Page-Apps (SPA und PWA)

In Apps mit React, Vue, Angular und ähnlichen Frameworks wird die Seite nicht neu geladen, daher muss die App Seitenaufrufe selbst senden: Rufen Sie cdp.page() nach jedem Bildschirmwechsel auf, aber nicht zweimal für das erste Laden – das hat der Installationscode bereits gesendet. Läuft der Router-Hook auch beim ersten Laden (afterEach in Vue Router, useEffect in React), entfernen Sie stattdessen cdp.page() aus dem Installationscode – ein Beispiel finden Sie auf dem Tab Installation.

// nach jedem Bildschirmwechsel, wenn der Router die Adresse bereits geändert hat
cdp.page();

// ein Bildschirm ohne eigene Adresse oder die Adresse hat sich noch nicht geändert
cdp.page('Warenkorb', { path: '/cart', title: 'Warenkorb' });

Hat ein Bildschirm keine eigene Adresse (ein Dialog, ein Checkout-Schritt, eine PWA ohne Adressen) oder ändert der Router die Adresse erst später, übergeben Sie die Seite ausdrücklich: path oder url (auch relativ) und den Titel. Diese Seite gelangt in den Seitenaufruf und in den Kontext der folgenden Ereignisse – etwa wird ein „In den Warenkorb“ dem Warenkorb-Bildschirm zugeordnet –, bis cdp.page() erneut aufgerufen wird. Als Referrer des zweiten und weiterer Bildschirme gilt der vorherige Bildschirm, die UTM-Parameter des Besuchs merkt sich der Tracker, bis der Tab geschlossen wird.

Anmeldung und Abmeldung von Kunden

Rufen Sie nach Anmeldung oder Registrierung cdp.identify() mit der Benutzer-ID aus Ihrem System auf – der Besuchsverlauf wird dann mit dem Kundenprofil verknüpft:

cdp.identify('user-42', { email: '[email protected]' });

Übergeben Sie die User ID nur für angemeldete Benutzer und verwenden Sie keine gemeinsamen Werte wie 0 oder guest: Profile mit gleicher User ID werden zusammengeführt. Rufen Sie bei der Abmeldung cdp.reset() auf, damit die nächste Person an diesem Computer eine neue Kennung erhält.

Welche Kennungen jeder Kanal braucht und wie sie ins Profil gelangen, zeigt die Tabelle Kundenidentifikation auf dem Tab Produktereignisse: email für E-Mail-Kampagnen, phone im internationalen Format für SMS, WhatsApp und Viber per Nummer, für Telegram- und Viber-Bots die Verknüpfung des Chats über einen Link, den Ihr Server erstellt. Übergeben Sie alles, was Sie über den Kunden wissen: Je mehr Kennungen, desto mehr Kanäle stehen zur Verfügung.

Anmeldesignatur

Der Tracker-Code mit dem Schreibschlüssel ist für alle sichtbar. Ohne Prüfung kann deshalb jeder Besucher cdp.identify() mit einer fremden User ID aufrufen. Sein Browser wird dann mit dem Profil eines anderen Kunden verknüpft: Empfehlungen, Nachrichten auf der Website und der Chat-Bot zeigen fremde Daten, und ein Benachrichtigungsabo erhält fremde Benachrichtigungen. Die Anmeldesignatur verhindert das: Der Server Ihrer Website signiert die User ID des angemeldeten Kunden, und OneTrace.pro prüft die Signatur.

  1. Öffnen Sie Website → Anbindung, den Tab Server, und klicken Sie auf Signaturschlüssel erstellen. Der Schlüssel wird einmal angezeigt: Speichern Sie ihn in der Umgebungsvariable CDP_IDENTITY_KEY des Servers und legen Sie ihn nicht in den Code der Seiten.

  2. Berechnen Sie auf dem Server Ihrer Website die Signatur – HMAC-SHA256 der User ID mit diesem Schlüssel – und übergeben Sie sie dem Tracker als drittes Argument von cdp.identify():

    <?php $userHash = hash_hmac('sha256', (string) $user->id, getenv('CDP_IDENTITY_KEY')); ?>
    <script>cdp.identify(<?= json_encode((string) $user->id) ?>, {}, { userHash: <?= json_encode($userHash) ?> });</script>
    

    Beispiele in Go, Node.js und Python finden Sie auf demselben Tab. Der Tracker merkt sich die Signatur und sendet sie mit Ereignissen, Chat-Nachrichten, Formularen und dem Benachrichtigungsabo.

  3. Beobachten Sie die Zähler auf der Karte Anmeldesignatur: wie viele Nachrichten mit User ID in den letzten 24 Stunden mit und ohne Signatur eingegangen sind. Wenn keine Nachrichten ohne Signatur mehr kommen, aktivieren Sie Signatur verlangen. Danach wird eine User ID ohne gültige Signatur nicht angenommen, und solche Besuche bleiben anonym.

Plugins und Bibliotheken senden die Signatur selbst, sobald der Signaturschlüssel eingetragen ist (die Plugins zeigen ihre Einstellungen auf Englisch):

  • WooCommerce ab 1.15: WooCommerce → Settings → OneTrace.pro → Identity key oder die Konstante ONETRACE_IDENTITY_KEY in wp-config.php;
  • Magento 2 ab 1.12: Stores → Configuration → OneTrace.pro → Connection → Identity key;
  • 1C-Bitrix ab 1.11: Identity key auf dem Tab der Website in den Einstellungen des OneTrace.pro-Moduls;
  • Laravel-Paket ab 1.14: die Variable ONETRACE_IDENTITY_KEY; PHP SDK ab 1.17: die Option identity_key und die Methode userHash();
  • mobile Apps mit SDK ab 1.1: Der Server Ihrer App berechnet die Signatur nach der Anmeldung, und die App übergibt sie zusammen mit der User ID an identify.

Aktivieren Sie die Pflichtsignatur, wenn Website und Apps aktualisiert sind und der Zähler der Nachrichten ohne Signatur null zeigt. Ein Server, der Ereignisse mit dem geheimen Schlüssel sendet, braucht keine Signatur.

Mit Schlüssel wechseln ersetzen Sie den Schlüssel: Der bisherige wird noch 24 Stunden akzeptiert. Ersetzen Sie ihn in dieser Zeit auf der Website und in Ihren Apps. Den Schlüssel erstellen und wechseln sowie die Pflichtsignatur aktivieren können Inhaber und Administrator.

Sprache der Kunden

Der Tracker übermittelt die Browsersprache; sie wird im Kundenprofil gespeichert (Merkmal language), bis die Sprache ausdrücklich gesetzt wird. Nach dieser Sprache wählen Journeys und Kampagnen die Sprachversion einer Vorlage. Die Projektsprachen sehen Sie im Block Sprache der Kunden auf dem Tab Installation.

Hat die Website eine Sprachauswahl, melden Sie die Wahl der Besucher — sie wird gespeichert und ins Profil geschrieben:

cdp.setLanguage('de');

Eine andere Quelle legen Sie bei der Initialisierung fest: language: 'page' — das Attribut lang von <html>, ein Sprachcode — eine Sprache für die ganze Website, false — keine Sprache übermitteln. Eine in Ihrem System bekannte Sprache können Sie als Merkmal übergeben: cdp.identify('user-42', { language: 'de' }).

Produktereignisse

Der Tab Produktereignisse zeigt fertige Aufrufe für fünf Aktionen: Produktansicht, In den Warenkorb, Bestellung, Merkliste und Anmeldung und Registrierung. Ereignisnamen und die Eigenschaft mit der Produkt-ID (standardmäßig product_id) stammen aus den Einstellungen im Bereich Empfehlungen. Sind dort keine Ereignisse gewählt, sehen Sie eine Warnung, und die Beispiele verwenden die Standardnamen: product_viewed, add_to_cart, order_completed.

Beispiel für eine Bestellung – alle Produkte werden im Array products übergeben:

cdp.track('order_completed', {
  order_id: 'A-1001',
  amount: 9980,
  products: [{ product_id: 'SKU-1', quantity: 2, price: 4990 }],
});

Merkliste ist optional: Die Ereignisse add_to_wishlist und remove_from_wishlist nutzen Journeys, die über Preissenkungen und wieder verfügbare Produkte der Merkliste informieren. Rufen Sie cdp.addToWishlist('SKU-1') und cdp.removeFromWishlist('SKU-1') auf oder verzichten Sie auf Code: Geben Sie der Schaltfläche das Attribut data-cdp-wishlist="SKU-1" (hinzufügen) oder data-cdp-wishlist-remove="SKU-1" (entfernen) – der Tracker sendet das Ereignis beim Klick.

Produktfragen – <div data-cdp-ask data-product-id="SKU-1"></div> auf der Produktseite: ein Block, in dem Kunden die KI zum Produkt fragen, siehe Produktfragen.

Jeder Schritt hat einen Vermerk: wie viele Ereignisse in 7 Tagen eingegangen sind und wann das letzte, oder „Keine Ereignisse in 7 Tagen“. So sehen Sie, welche Aufrufe noch nicht funktionieren. Die Produkt-ID muss mit der ID im Produktkatalog übereinstimmen.

Tab „Produktereignisse“ mit Vermerken zu eingegangenen Ereignissen

Bestellungen und Registrierungen senden Sie zuverlässiger von Ihrem Server – siehe Serverseitige Integration.

Einladungslinks

Sind im Treueprogramm Einladungen aktiviert, hat jedes Mitglied einen Link zu Ihrer Website mit dem Parameter ?ref=CODE. Der Tracker erkennt diesen Parameter selbst: Er speichert den Code 30 Tage lang im Cookie cdp_ref und sendet einmalig das Ereignis referral_visited. Der Freund wird gezählt, sobald er sich registriert oder auf der Website anmeldet. Shop-Plugins übergeben den Code aus dem Cookie bei der Registrierung, eine eigene Website über die API.

Web Push

Die Seite Website → Web Push zeigt, ob der Kanal verbunden ist und wie viele Abonnements es gibt. Fehlt der Kanal, legen Sie ihn über den Link Integrationen öffnen an – die Schlüssel werden automatisch erzeugt (siehe Integrationen und Kanäle). Dann:

  1. Service-Worker-Datei. Legen Sie im Stammverzeichnis der Website die Datei cdp-sw.js mit einer Zeile an:
    importScripts('https://cdp.onetrace.pro/tracker/cdp-sw.js');
    
  2. Abonnieren-Schaltfläche. Fügen Sie Ihrer Website eine Schaltfläche hinzu, die beim Klick cdp.push.subscribe() aufruft. Der Browser fragt die Erlaubnis für Benachrichtigungen nur nach einer Aktion des Besuchers ab.

Benachrichtigungen funktionieren nur auf Websites mit HTTPS. Das Abonnement wird mit dem Profil des Besuchers verknüpft.

Seite „Web Push“: Kanalstatus und Code für die Website

CMS und Google Tag Manager

Auf dem Tab CMS und GTM finden Sie Schritt-für-Schritt-Anleitungen für eine eigene Website, Google Tag Manager, 1C-Bitrix, Tilda, WordPress und WooCommerce sowie InSales: wohin der Installationscode, die Ereignisse und die Widgets gehören.

In Google Tag Manager erstellen Sie zum Beispiel ein Tag „Benutzerdefiniertes HTML“ mit dem Installationscode und dem Trigger „Alle Seiten“. Für Produktereignisse brauchen Sie eigene Tags mit dem Aufruf cdp.track und Triggern auf dataLayer-Ereignisse (view_item, add_to_cart, purchase). Prüfen Sie nach dem Veröffentlichen des Containers auf dem Tab Installation, ob Ereignisse ankommen.

Anbindung mit einem KI-Agenten

Wenn ein Entwickler Ihre Website mit einem KI-Agenten erstellt (Claude Code, Codex, Cursor und andere), geben Sie dem Agenten einen fertigen Skill. Klicken Sie auf dem Tab KI-Agent auf SKILL.md herunterladen. Die Datei enthält eine Anleitung für den Agenten auf Englisch mit den Daten Ihres Projekts: die Adresse von OneTrace.pro, den ausgewählten Schreibschlüssel, die Namen der Produktereignisse, die Widgets und den Status von Web Push. Damit fügt der Agent den Installationscode, die Produktereignisse, An- und Abmeldung, Widgets und das Abonnieren von Benachrichtigungen selbst ein.

  1. Wenn es mehrere Schreibschlüssel gibt, wählen Sie den gewünschten aus.
  2. Laden Sie die Datei herunter und legen Sie sie im Projekt der Website ab: für Claude Code unter .claude/skills/<Skill-Name>/SKILL.md, für andere Agenten mit Unterstützung für Agent Skills in deren Skill-Ordner, zum Beispiel .agents/skills/<Skill-Name>/SKILL.md. Der genaue Pfad steht auf dem Tab. Sie können die Datei auch einfach an Ihre Nachricht an den Agenten anhängen.
  3. Geben Sie dem Agenten die Aufgabe – ein Beispieltext steht auf dem Tab.

Tab „KI-Agent“: Skill mit den Projektdaten für einen KI-Agenten

Geheime Schlüssel gelangen nie in den Skill. Wenn Sie die Ereignisse in den Empfehlungseinstellungen ändern oder Widgets hinzufügen, laden Sie den Skill erneut herunter.

Wichtig zu wissen

  • Suchmaschinen-Crawler, Link-Vorschauen von Messengern, Website-Prüfdienste und automatisierte Browser werden nicht erfasst: Der Tracker sendet für sie keine Ereignisse und setzt keine Cookies, zeigt aber Empfehlungs-Widgets an. Um alle Besucher zu erfassen, ergänzen Sie den Installationscode um die Option: cdp.init('…', { host: '…', ignoreBots: false }).
  • Der Tracker merkt sich die Klick-IDs von Anzeigen (gclid, yclid, fbclid, rb_clickid und weitere) sowie die Pixel-Cookies von Meta und Metrica: Anhand dieser Daten finden die Werbe-Conversions den Klick, nach dem jemand gekauft hat.
  • Der Tracker sammelt Ereignisse und sendet sie in Paketen. Bricht die Verbindung ab, werden die Ereignisse im Browser gespeichert und später gesendet.
  • Alle Ereignisse der Website sehen Sie in Echtzeit im Bereich Ereignisse.
  • Empfehlungs-Widgets richten Sie im Bereich Website → Widgets ein – siehe Empfehlungs-Widgets auf der Website.