Der Google Tag Manager (GTM) ist eine der empfohlenen Möglichkeiten, das Positive User Tracking-Skript auf Ihrer Website bereitzustellen. Sobald GTM das Skript ausliefert, beginnt Positive User mit dem Tracking der Besucher, erstellt Kontaktprofile und ermöglicht es Ihnen, diese Profile mit den für Ihr Unternehmen relevanten Daten anzureichern.
Diese Anleitung behandelt drei Themen:
Installation des grundlegenden Implementierungsskripts;
Identifizierung von Kontakten mit einer Contact ID;
Erweiterung des Setups mit zusätzlichen Kontaktdaten und Callbacks.
Ein aktiver Positive User Workspace.
Workspace-Key und Subdomain-Informationen (zu finden unter „Workspace Einstellungen" → „API & Integrations" → „Setup & Integrations").
Zugriff auf den GTM-Container, der auf Ihrer Website installiert ist.
Eine bestehende Cookie-/Einwilligungsstrategie.
Falls Ihre Website eine Content Security Policy verwendet, stellen Sie sicher, dass die Positive User Domains auf der Whitelist stehen.
Das Implementierungsskript definiert ein Konfigurationsobjekt (window.civchat) und lädt anschließend „widget.js". Wenn Sie es über GTM einbinden, können Sie es bereitstellen, aktualisieren oder pausieren, ohne den Website-Code erneut anfassen zu müssen.
Workspace-Key und Subdomain abrufen
Gehen Sie in Ihrem Positive User Workspace zu „Workspace Einstellungen" → „API & Integrations" → „Setup & Integrations", um Ihren Workspace-Key zu finden, und notieren Sie sich Ihre Workspace-Subdomain (z. B. yourapp.user.com).
Custom-HTML-Tag im GTM erstellen
Melden Sie sich in Ihrem GTM-Container an und gehen Sie zu „Tags" → „Neu" → „Tag-Konfiguration" → „Benutzerdefiniertes HTML" und fügen Sie das folgende Skript ein. Ersetzen Sie YOUR_KEY durch den Workspace-Key aus Schritt 1 und yourapp.user.com durch Ihre Workspace-Subdomain:
<script data-cfasync="false" type="text/javascript">
window.civchat = {
apiKey: 'YOUR_KEY'
};
</script>
<script data-cfasync="false" src="https://yourapp.user.com/widget.js"></script>
Trigger im GTM-Container festlegen
Wählen Sie unter „Trigger" den Trigger, der zu Ihrer Einwilligungskonfiguration passt – in der Regel ist das ein „cookie_consent_update"-Event (oder dessen Entsprechung). Auf diese Weise wird das Skript erst geladen, nachdem der Besucher Cookies akzeptiert hat. Falls Sie keine Einwilligungsebene haben, funktioniert „Alle Seiten" als Ausgangspunkt.
Speichern, Vorschau, Veröffentlichen
Benennen Sie das Tag (zum Beispiel „Positive User – Tracking-Skript"), klicken Sie auf „Speichern" und starten Sie anschließend den „Vorschau"-Modus in GTM, um zu bestätigen, dass das Tag ausgelöst wird und das Widget geladen wird. Nach erfolgreicher Prüfung senden und veröffentlichen Sie den GTM-Container.
Tipp: Um zu prüfen, ob das Skript auf einer Seite vollständig geladen ist, öffnen Sie die Browser-Konsole und führen Sie
typeof UE === 'object' && typeof userengage === 'function'aus. Wenn true zurückgegeben wird, ist Positive User einsatzbereit.
Standardmäßig verfolgt Positive User Besucher anonym über ein Cookie (__ca__chat). Um einen anonymen Besucher in einen erkannten Kontakt zu verwandeln – und um dessen Verlauf über Geräte und Sitzungen hinweg konsistent zu halten – übergeben Sie eine Contact ID über das Feld (Attribut) „user_id" auf „window.civchat".
Die richtige Contact ID wählen
Der Wert, den Sie als Contact ID verwenden, hängt davon ab, wie Ihr Unternehmen Personen identifiziert. Es gibt keine einzige richtige Wahl; es sollte ein stabiler, eindeutiger Identifikator sein, den Sie konsistent an allen Touchpoints übergeben können. Die drei häufig verwendeten Optionen sind:
Interne Datenbank-ID: die stabilste Option, da sie sich niemals ändert, selbst wenn der Kontakt seine E-Mail-Adresse aktualisiert. Wird in den Beispielen in diesem Artikel verwendet.
E-Mail-Adresse in Kleinbuchstaben: einfach zu implementieren und im Workspace lesbar, aber an die aktuelle E-Mail-Adresse des Kontakts gebunden.
SHA-256-Hash der E-Mail-Adresse in Kleinbuchstaben: gleiche Eindeutigkeit wie die E-Mail-Adresse, jedoch werden keine unverschlüsselten personenbezogenen Daten über GTM oder Browser-Variablen übertragen.
Mehr zu IDs erfahren Sie in unserem Artikel. [LINK]
Wählen Sie eine Strategie und behalten Sie diese auf Ihrer gesamten Website und in allen Umgebungen bei. Ein späterer Wechsel des Contact-ID-Formats kann zu doppelten Kontaktprofilen oder unterbrochener Tracking-Kontinuität führen.
Die Contact ID muss verfügbar sein, wenn „window.civchat" definiert wird – also bevor „widget.js" geladen wird. Der Standardansatz besteht darin, sie aus dem dataLayer auszulesen, den Ihre Website für eingeloggte Kontakte befüllt, und sie dann bedingt dem „civchat"-Objekt zuzuweisen.
Contact ID im dataLayer finden
Auf den meisten E-Commerce-Plattformen (Magento, Shopify, WooCommerce, PrestaShop usw.) ist der dataLayer bereits mit Informationen zum eingeloggten Kunden befüllt – einschließlich Kunden-ID, E-Mail und grundlegender Profilfelder. Sie müssen kein JavaScript selbst schreiben; Sie müssen lediglich wissen, welcher dataLayer-Schlüssel den Wert enthält, den Sie als Contact ID verwenden möchten.
So prüfen Sie, was verfügbar ist:
Öffnen Sie GTM und klicken Sie oben rechts auf „Vorschau".
Geben Sie Ihre Website-URL ein und melden Sie sich im Vorschaufenster als Testkunde an.
Öffnen Sie im GTM Tag Assistant den Tab „Data Layer" bei einem beliebigen Event.
Durchsuchen Sie die Einträge nach einem Objekt, das Kunden- oder Nutzerinformationen enthält. Häufige Schlüsselnamen sind „visitorId", „user_id", „customerId" oder ähnliche.
Falls die Contact ID nicht in Ihrem DataLayer vorhanden ist: Wenden Sie sich an Ihren Entwickler oder Plattform-Administrator und bitten Sie ihn, für eingeloggte Nutzer einen stabilen Kundenidentifikator in den dataLayer zu pushen. Dies ist eine kleine Anpassung auf Plattformseite und eine gängige Anforderung für jedes Tracking- oder Personalisierungstool, das über GTM integriert wird.
dataLayer-Variable in GTM erstellen oder wiederverwenden
Gehen Sie in GTM zu „Variablen" und prüfen Sie, ob bereits eine Variable für Ihre Kunden-ID existiert – in Containern, die von einer Agentur eingerichtet wurden oder für eine bestehende Analytics-Integration bestehen, ist das häufig der Fall. Suchen Sie nach Variablen des Typs „Datenschicht-Variable", die auf Schlüssel wie „customer_id" oder „user_id" verweisen. Falls bereits eine vorhanden ist, können Sie diese wiederverwenden und direkt zum nächsten Schritt übergehen.
Falls noch keine existiert, gehen Sie zu „Variablen" → „Neu" → „Datenschicht-Variable" und erstellen Sie eine. Geben Sie im Feld „Name der Datenschicht-Variable" den exakten Schlüsselnamen ein, den Sie in Ihrem dataLayer gefunden haben (zum Beispiel „customer_id"). Benennen Sie die Variable mit einem eindeutigen Namen, z. B. „DLV – user_id".
Tag aktualisieren
Bearbeiten Sie das Custom-HTML-Tag und weisen Sie die Contact ID bedingt zu, sodass sie nur hinzugefügt wird, wenn der Besucher tatsächlich eingeloggt ist:
<script data-cfasync="false" type="text/javascript">
var civchatConfig = {
apiKey: 'YOUR_KEY'
};
if ({{DLV - user_id}}) {
civchatConfig.user_id = {{DLV - user_id}};
}
window.civchat = civchatConfig;
</script>
<script data-cfasync="false" src="https://yourapp.user.com/widget.js"></script>
Wenn „user_id" vorhanden ist, verwendet Positive User diese als primären Identifikator. Existiert die ID bereits in Ihrem Workspace, wird das Tracking auf das Profil dieses Kontakts umgeschaltet; falls nicht, wird die ID der aktuellen anonymen Sitzung zugewiesen und ein neuer Kontakt erstellt.
Sobald ein Kontakt identifiziert ist, können Sie sein Profil mit weiteren Attributen anreichern – den Datenfeldern, die auf dem Kontaktprofil gespeichert werden. Übergeben Sie diese Werte auf der obersten Ebene des civchat-Konfigurationsobjekts, neben „user_id":
<script data-cfasync="false" type="text/javascript">
var civchatConfig = {
apiKey: 'YOUR_KEY'
};
if ({{DLV - user_id}}) {
civchatConfig.user_id = {{DLV - user_id}};
civchatConfig.email = {{DLV - user_email}};
civchatConfig.first_name = {{DLV - user_first_name}};
civchatConfig.last_name = {{DLV - user_last_name}};
civchatConfig.phone_number = {{DLV - user_phone}};
// Custom attributes go at the same level
civchatConfig.plan_type = {{DLV - user_plan}};
}
window.civchat = civchatConfig;
</script>
<script data-cfasync="false" src="https://yourapp.user.com/widget.js"></script>
Einige Punkte, die Sie beachten sollten:
Standard- vs. benutzerdefinierte Attribute: Standardattribute (wie „Email", „Phone number", „Gender", „Status") werden von Positive User automatisch erkannt. Benutzerdefinierte Attribute (wie „Plan type") müssen bereits im Workspace vorhanden sein – erstellen Sie diese vorab. (Siehe „How to Create a Custom Attribute")
Das Format ist wichtig: Wählen Sie stets einen passenden Typ für das Attribut, da dieser die späteren Filtermöglichkeiten definiert. Eine vollständige Liste der Formatierungsregeln finden Sie in der Entwicklerdokumentation oder im Artikel „What Is an Attribute".
Werte überschreiben vorhandene Daten: Jedes Attribut, das Sie hier übergeben, ersetzt den Wert, der bereits auf dem Kontaktprofil gespeichert ist. Übergeben Sie Attribute nur, wenn Sie einen echten Wert haben – deshalb halten wir sie im „if"-Block oben.
Mit Callbacks kann Ihr Code auf Ereignisse innerhalb des Positive User Widgets reagieren – zum Beispiel, wenn das Widget fertig geladen ist oder eine neue Chat-Nachricht eintrifft. Sie werden als Funktionen innerhalb desselben „civchat"-Konfigurationsobjekts definiert, neben „apiKey" und „user_id".
Verfügbare Callbacks
Das Positive User SDK stellt die folgenden Callbacks bereit:
onLoad: wird ausgeführt, sobald das Widget-Skript und seine Ressourcen vollständig geladen wurden. Nützlich, um andere GTM-Tags zu koordinieren, die darauf angewiesen sind, dass Positive User bereit ist.
onMessage: wird jedes Mal ausgeführt, wenn eine Chat-Nachricht empfangen wird. Das „message"-Objekt enthält ein „isAdmin"-Flag, das angibt, ob die Nachricht von einem Nutzer/einer Automatisierung (true) oder vom Kontakt (false) stammt.
onOpen / onClose: wird ausgeführt, wenn das Chat-Widget erweitert oder minimiert wird.
onPayloadReceived: wird ausgeführt, wenn das Widget einen Payload vom Automatisierungsmodul „Send Code" empfängt.
Die vollständige Referenz finden Sie in der Entwicklerdokumentation.
Das folgende Skript zeigt ein vollständiges Setup, das alles aus dieser Anleitung kombiniert: den onLoad-Callback, die Contact ID, die E-Mail-Adresse und zusätzliche Kontaktdaten. Diese Version können Sie als Ausgangspunkt in der Produktion verwenden:
<script data-cfasync="false" type="text/javascript">
var civchatConfig = {
apiKey: 'YOUR_KEY',
// Notify GTM once the widget is fully loaded
onLoad: function() {
dataLayer.push({ event: 'Positive User - Widget Ready' });
}
};
// Identify the contact and pass their data only when logged in
if ({{DLV - user_id}}) {
civchatConfig.user_id = {{DLV - user_id}};
civchatConfig.email = {{DLV - user_email}};
civchatConfig.first_name = {{DLV - user_first_name}};
civchatConfig.last_name = {{DLV - user_last_name}};
civchatConfig.phone_number = {{DLV - user_phone}};
civchatConfig.plan_type = {{DLV - user_plan}};
}
window.civchat = civchatConfig;
</script>
<script data-cfasync="false" src="https://yourapp.user.com/widget.js"></script>
In GTM können Sie anschließend einen Trigger vom Typ „Benutzerdefiniertes Ereignis" erstellen, der auf „Positive User – Widget Ready" hört, und ihn für jedes Tag verwenden, das das Positive User SDK benötigt.
GTM ist praktisch, fügt aber eine zusätzliche Ebene zwischen Ihrer Website und Positive User ein. Falls das Skript nicht auszulösen scheint:
Prüfen Sie den „Vorschau"-Modus von GTM, um zu bestätigen, dass das Tag tatsächlich auf der Seite ausgeführt wird.
Stellen Sie sicher, dass der GTM-Container veröffentlicht und nicht nur gespeichert ist.
Prüfen Sie die Browser-Konsole auf JavaScript-Fehler, die die Ausführung des Skripts verhindern könnten.
Vergewissern Sie sich, dass Adblocker, Consent-Management-Tools oder Ihre CSP GTM oder die Positive User Domain nicht blockieren.
Prüfen Sie, ob dataLayer-Variablen im Vorschaumodus korrekt aufgelöst werden – wenn eine Variable leer ist, ist auch das entsprechende Feld auf „civchat" leer.
How to Configure a Chat Widget [LINK]
IDs Concept [LINK]