Über das Braze Internet-SDK

Das Braze Internet-SDK ermöglicht es Ihnen, Analytics zu erfassen und Ihren Internet-Nutzer:innen umfangreiche In-App-Nachrichten, Push-Benachrichtigungen und Content-Card-Nachrichten anzuzeigen. Weitere Informationen finden Sie in der Braze JavaScript-Referenzdokumentation.

Hinweis

Diese Anleitung verwendet Codebeispiele aus dem Braze Web SDK 4.0.0+. Um ein Upgrade auf die neueste Web SDK-Version durchzuführen, siehe SDK Upgrade Guide.

Das Internet-SDK integrieren

Sie können das Internet-SDK von Braze mit den folgenden Methoden integrieren. Weitere Optionen finden Sie unter Andere Integrationsmethoden.

• Code-basierte Integration: Integrieren Sie das Internet-SDK von Braze direkt in Ihre Codebasis mit Ihrem bevorzugten Paketmanager oder dem Braze-CDN. So haben Sie die volle Kontrolle darüber, wie das SDK geladen und konfiguriert wird.
• Google Tag Manager: Eine No-Code-Lösung, mit der Sie das Internet-SDK von Braze integrieren können, ohne den Code Ihrer Website zu ändern. Weitere Informationen finden Sie unter Google Tag Manager mit dem Braze SDK.

Wichtig

Wir empfehlen die Verwendung der NPM-Integrationsmethode. Zu den Vorteilen gehören die lokale Speicherung von SDK-Bibliotheken auf Ihrer Website, Schutz vor Werbeblocker-Erweiterungen und kürzere Ladezeiten durch Bundler-Unterstützung.

• code-basierte integration
• google tag manager

Schritt 1: Die Braze-Bibliothek installieren

Sie können die Braze-Bibliothek mit einer der folgenden Methoden installieren. Falls Ihre Website jedoch eine Content-Security-Policy verwendet, lesen Sie zunächst die Content Security Policy.

Wichtig

Obwohl die meisten Werbeblocker das Braze Internet-SDK nicht blockieren, sind einige restriktivere Werbeblocker dafür bekannt, Probleme zu verursachen.

• package manager:in
• braze cdn

Falls Ihre Website NPM- oder Yarn-Paketmanager verwendet, können Sie das Braze NPM-Paket als Abhängigkeit hinzufügen.

TypeScript-Definitionen sind seit v3.0.0 enthalten. Hinweise zum Upgrade von 2.x auf 3.x finden Sie in unserem Changelog.

1
2
3

npm install --save @braze/web-sdk
# or, using yarn:
# yarn add @braze/web-sdk

Nach der Installation können Sie die Bibliothek wie gewohnt mit import oder require einbinden:

1
2
3

import * as braze from "@braze/web-sdk";
// or, using `require`
const braze = require("@braze/web-sdk");

Fügen Sie das Braze Internet-SDK direkt zu Ihrem HTML hinzu, indem Sie unser CDN-gehostetes Skript referenzieren, das die Bibliothek asynchron lädt.

Wichtig

Die Standard-Einstellung Seitenübergreifendes Tracking verhindern in Safari kann dazu führen, dass In-App-Nachrichtentypen wie Banner und Content Cards bei Verwendung der CDN-Integrationsmethode nicht angezeigt werden. Um dieses Problem zu vermeiden, verwenden Sie die NPM-Integrationsmethode, damit Safari diese Nachrichten nicht als seitenübergreifenden Datenverkehr einstuft und Ihre Web-Nutzer:innen sie in allen unterstützten Browsern sehen können.

Schritt 2: Das SDK initialisieren

Nachdem das Braze Internet-SDK zu Ihrer Website hinzugefügt wurde, initialisieren Sie die Bibliothek mit dem API-Schlüssel und der SDK-Endpunkt-URL, die Sie im Braze-Dashboard unter Einstellungen > App-Einstellungen finden. Eine vollständige Liste der Optionen für braze.initialize() sowie unsere weiteren JavaScript-Methoden finden Sie in der Braze JavaScript-Dokumentation.

Hinweis

Angepasste Domains für Internet-SDK-Anfragen werden nicht unterstützt: Die baseUrl des Internet-SDK muss ein Braze-SDK-Endpunkt sein (z. B. sdk.iad-05.braze.com). Braze unterstützt kein Routing von Internet-SDK-Datenverkehr über eine kundeneigene Domain via CNAME-Einträge. Falls Sie benötigen, dass Internet-SDK-Anfragen von Ihrer eigenen Domain ausgehen, wenden Sie sich an den Braze-Support.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

// initialize the SDK
braze.initialize('YOUR-API-KEY-HERE', {
    baseUrl: "YOUR-SDK-ENDPOINT-HERE",
    enableLogging: false, // set to `true` for debugging
    allowUserSuppliedJavascript: false, // set to `true` to support custom HTML messages
});

// Enable automatic display of in-app messages
// Required if you want in-app messages to display automatically when triggered
braze.automaticallyShowInAppMessages();

// if you use Content Cards
braze.subscribeToContentCardsUpdates(function(cards){
    // cards have been updated
});

// optionally set the current user's external ID before starting a new session
// you can also call `changeUser` later in the session after the user logs in
if (isLoggedIn){
    braze.changeUser(userIdentifier);
}

// `openSession` should be called last - after `changeUser` and `automaticallyShowInAppMessages`
braze.openSession();

Wichtig

Anzeige von In-App-Nachrichten: Um In-App-Nachrichten automatisch anzuzeigen, wenn sie getriggert werden, müssen Sie braze.automaticallyShowInAppMessages() aufrufen. Ohne diesen Aufruf werden In-App-Nachrichten nicht automatisch angezeigt. Falls Sie die Nachrichtenanzeige manuell steuern möchten, entfernen Sie diesen Aufruf und verwenden Sie stattdessen braze.subscribeToInAppMessage(). Weitere Informationen finden Sie unter Automatische Trigger deaktivieren.

Fehlerbehebung bei fehlenden Sitzungen für anonyme Nutzer:innen

Falls Sie ein Verhalten beobachten, bei dem Sitzungen fehlen, oder Sie die Sitzung für Nutzer:innen, die auf der Website anonym bleiben, nicht verfolgen können, stellen Sie sicher, dass Ihre Integration braze.openSession() während der Initialisierung aufruft.

• Szenario: Anonyme Nutzer:innen können eine Braze-ID zurückgeben, aber Sitzungsdaten sind leer oder fehlen.
• Ursache: Die Implementierung ruft braze.openSession() nicht auf.
• Lösung: Rufen Sie braze.openSession() immer nach der Initialisierung auf (und nach braze.changeUser(), falls Sie eine externe ID setzen).

Weitere Informationen finden Sie unter Schritt 2: Das SDK initialisieren.

Wichtig

Anonyme Nutzer:innen auf Mobilgeräten oder im Internet können zu Ihren MAU gezählt werden. Daher kann es sinnvoll sein, das SDK bedingt zu laden oder zu initialisieren, um diese Nutzer:innen von Ihrer MAU-Zählung auszuschließen.

Voraussetzungen

Bevor Sie diese Integrationsmethode verwenden können, müssen Sie ein Konto und einen Container für Google Tag Manager erstellen.

1. Schritt: Tag-Template-Galerie öffnen

Wählen Sie im Google Tag Manager Ihren Workspace aus und wählen Sie dann Templates. Wählen Sie im Bereich Tag Template die Option Search Gallery.

2. Schritt: Initialisierungs-Tag-Template hinzufügen

Suchen Sie in der Template-Galerie nach braze-inc und wählen Sie dann Braze Initialization Tag aus.

Wählen Sie Add to workspace > Add.

3. Schritt: Tag konfigurieren

Wählen Sie im Abschnitt Templates Ihr neu hinzugefügtes Template aus.

Wählen Sie das Bleistift-Symbol, um das Dropdown-Menü Tag Configuration zu öffnen.

Geben Sie die erforderlichen Mindestinformationen ein:

Feld	Beschreibung
API Key	Ihr Braze-API-Schlüssel, den Sie im Braze-Dashboard unter Settings > App Settings finden.
API Endpoint	Ihre REST-Endpunkt-URL. Ihr Endpunkt hängt von der Braze-URL für Ihre Instanz ab.
SDK Version	Die aktuellste MAJOR.MINOR-Version des Web Braze SDK, die im Changelog aufgeführt ist. Wenn die neueste Version beispielsweise 4.1.2 ist, geben Sie 4.1 ein. Weitere Informationen finden Sie unter Über die SDK-Versionsverwaltung.

Für zusätzliche Initialisierungseinstellungen wählen Sie Braze Initialization Options und wählen die gewünschten Optionen aus.

4. Schritt: Initialisierungsoptionen auswählen

Das Braze Initialization Tag bietet die folgenden Optionen. Die meisten davon lassen sich direkt den Web SDK InitializationOptions zuordnen, und einige entsprechen Web-SDK-Methoden, die das Tag während der Initialisierung aufruft. Wählen Sie die Optionen aus, die Ihren Integrationsanforderungen entsprechen:

GTM-Option	Web-SDK-Konfiguration oder -Methode	Beschreibung
Allow HTML In-App Messages	allowUserSuppliedJavascript	Aktiviert HTML-In-App-Nachrichten, Banner und von Nutzer:innen bereitgestellte JavaScript-Klickaktionen. Erforderlich für HTML-In-App-Nachrichten und Banner, die angepasstes HTML verwenden. Aktivieren Sie diese Option nur, wenn Sie dem HTML- und JavaScript-Inhalt vertrauen, da sie die Ausführung von benutzerdefiniertem JavaScript ermöglicht.
App Version Number	appVersion, appVersionNumber	App-Version für die Segmentierung (zum Beispiel 1.2.3.4).
Automatically Open New Session	braze.openSession()	Öffnet eine neue Sitzung, nachdem das SDK initialisiert wurde, indem diese Methode automatisch aufgerufen wird.
Automatically show new in app messages	braze.automaticallyShowInAppMessages()	Zeigt neue In-App-Nachrichten automatisch an, wenn sie vom Server eintreffen, indem diese Methode nach der Initialisierung aufgerufen wird.
Disable Automatic Push-Token Maintenance	disablePushTokenMaintenance	Verhindert, dass das SDK Push-Token bei neuen Sitzungen mit dem Braze-Backend synchronisiert.
Disable Automatic Service Worker Registration	manageServiceWorkerExternally	Verwenden Sie diese Option, wenn Sie den Service Worker selbst registrieren und verwalten.
Disable Cookies	noCookies	Verwendet localStorage anstelle von Cookies für Nutzer:innen- und Sitzungsdaten. Verhindert die subdomainübergreifende Erkennung.
Disable Font Awesome	doNotLoadFontAwesome	Verhindert, dass das SDK Font Awesome aus dem CDN lädt. Verwenden Sie diese Option, wenn Ihre Website bereits über eine eigene Font-Awesome-Version verfügt.
Enable SDK Authentication	enableSdkAuthentication	Aktiviert die SDK-Authentifizierung.
Enable Web SDK Logging	enableLogging	Aktiviert die Konsolenprotokollierung für das Debugging. Entfernen Sie diese Option vor dem Produktivbetrieb.
Minimum Interval Between Triggered Messages	minimumIntervalBetweenTriggerActionsInSeconds	Mindestzeit in Sekunden zwischen getriggerten Aktionen (Standard: 30).
Open Cards in New Tab	openCardsInNewTab	Öffnet Content-Card-Links in einem neuen Tab, wenn die Standard-Feed-UI verwendet wird.
Service Worker Location	serviceWorkerLocation	Benutzerdefinierter Pfad für die Service-Worker-Datei (Standard: /service-worker.js).
Session Timeout (seconds)	sessionTimeoutInSeconds	Sitzungszeitlimit in Sekunden (Standard: 1800).

Hinweis

Um angepasste HTML-In-App-Nachrichten bei Verwendung des Google Tag Manager Braze Initialization Tag zu aktivieren, wählen Sie Allow HTML In-App Messages in den Braze Initialization Options aus. Dieses Kontrollkästchen entspricht der Initialisierungsoption allowUserSuppliedJavascript in braze.initialize() und setzt sie auf true. Das Google Tag Manager Braze Initialization Tag verwendet dieses Label anstelle des Optionsnamens.

Für Optionen, die nicht im GTM-Template verfügbar sind (wie contentSecurityNonce, localization oder devicePropertyAllowlist), verwenden Sie stattdessen die Laufzeitinitialisierung.

5. Schritt: Auf allen Seiten triggern

Das Initialisierungs-Tag sollte auf allen Seiten Ihrer Website ausgeführt werden. So können Sie die Braze-SDK-Methoden nutzen und Web-Push-Analytics erfassen.

Wichtig

Tag-Reihenfolge: Das Braze Initialization Tag muss vor allen anderen Tags ausgelöst werden, die Braze-SDK-Methoden aufrufen (wie braze.getUser() oder braze.logCustomEvent()). Wenn angepasste Events, Nutzer:innen-Attribute oder andere Braze-Methodenaufrufe vor der SDK-Initialisierung ausgelöst werden, können Fehler wie Uncaught TypeError: Cannot read properties of undefined (reading 'getUser') auftreten. Um die richtige Reihenfolge sicherzustellen, konfigurieren Sie Ihr Braze Initialization Tag als Setup-Tag oder verwenden Sie die Tag-Sequenzierungsfunktion von GTM, um sicherzustellen, dass es zuerst ausgelöst wird. Weitere Informationen finden Sie unter Tag-Sequenzierung für Braze-Action-Tags.

6. Schritt: Integration überprüfen

Sie können Ihre Integration mit einer der folgenden Optionen überprüfen:

• Option 1: Mit dem Debugging-Tool von Google Tag Manager können Sie prüfen, ob das Braze Initialization Tag auf Ihren konfigurierten Seiten oder bei Ihren konfigurierten Ereignissen korrekt getriggert wird.
• Option 2: Prüfen Sie, ob von Ihrer Webseite Netzwerk-Anfragen an Braze gesendet werden. Darüber hinaus sollte die globale window.braze-Bibliothek nun definiert sein.

Bot-Traffic filtern

MAU kann einen Prozentsatz an Bot-Nutzer:innen enthalten, was die Anzahl Ihrer monatlich aktiven Nutzer:innen erhöht. Das Braze Web SDK verfügt zwar über eine integrierte Erkennung für einige gängige Webcrawler (wie Suchmaschinen-Bots und Social-Media-Vorschau-Bots), dennoch ist es besonders wichtig, proaktiv mit robusten Lösungen zur Erkennung von Bots zu arbeiten, da SDK-Updates allein nicht in der Lage sind, jeden neuen Bot konsistent zu erkennen.

Einschränkungen der Bot-Erkennung auf SDK-Seite

Das Web SDK umfasst eine grundlegende, auf User-Agents basierende Bot-Erkennung, die bekannte Crawler herausfiltert. Dieser Ansatz weist jedoch Einschränkungen auf:

• Es entstehen ständig neue Bots: KI-Unternehmen und andere Akteure entwickeln regelmäßig neue Bots, die sich möglicherweise tarnen, um einer Erkennung zu entgehen.
• User-Agent-Spoofing: Ausgefeilte Bots können legitime Browser-User-Agents imitieren.
• Angepasste Bots: Nicht-technische Nutzer:innen können nun auf einfache Weise Bots mithilfe großer Sprachmodelle (LLMs) erstellen, wodurch das Verhalten der Bots unvorhersehbar wird.

Implementierung von Bot-Filtern

Wichtig

Die nachfolgend aufgeführten Lösungen sind allgemeine Vorschläge. Passen Sie die Bot-Filterlogik an Ihre individuelle Umgebung und Ihre Datenverkehrsmuster an.

Die zuverlässigste Lösung besteht darin, Ihre eigene Bot-Filterlogik zu implementieren, bevor Sie das Braze SDK initialisieren. Zu den gängigen Ansätzen gehören:

Nutzerinteraktion erforderlich

Es wird empfohlen, die Initialisierung des SDK zu verzögern, bis Nutzer:innen eine sinnvolle Interaktion durchführen, wie beispielsweise das Akzeptieren eines Cookie-Consent-Banners, das Scrollen oder einen Klick. Dieser Ansatz ist häufig einfacher umzusetzen und kann beim Filtern von Bot-Traffic sehr effektiv sein.

Wichtig

Wenn Sie die Initialisierung des SDK bis zur Nutzerinteraktion verzögern, kann dies dazu führen, dass Banner und Content Cards ebenfalls erst nach dieser Interaktion angezeigt werden.

Erkennung angepasster Bots

Implementieren Sie eine angepasste Erkennung basierend auf Ihren spezifischen Bot-Traffic-Mustern, wie zum Beispiel:

• Analyse von User-Agent-Strings auf Muster, die Sie in Ihrem Datenverkehr identifiziert haben
• Überprüfung auf Indikatoren für einen Headless-Browser
• Nutzung von Bot-Erkennungsdiensten von Drittanbietern
• Überwachung von Verhaltenssignalen, die für Ihre Website spezifisch sind

Beispiel für bedingte Initialisierung:

1
2
3
4
5
6
7
8

// Only initialize Braze if your custom bot detection determines this is not a bot
if (!isLikelyBot()) {
  braze.initialize('YOUR-API-KEY-HERE', {
    baseUrl: "YOUR-SDK-ENDPOINT-HERE"
  });
  braze.automaticallyShowInAppMessages();
  braze.openSession();
}

Best Practices

• Analysieren Sie regelmäßig Ihre MAU-Daten und Web-Traffic-Muster, um neues Bot-Verhalten zu erkennen.
• Führen Sie gründliche Tests durch, um sicherzustellen, dass Ihre Bot-Filterung keine legitimen Nutzer:innen vom Tracking ausschließt.
• Aktualisieren Sie Ihre Filterlogik auf Grundlage der Bot-Traffic-Muster, die Sie in Ihrer Umgebung beobachten.

Optionale Konfigurationen

Protokollierung

Um die Protokollierung schnell zu aktivieren, können Sie ?brazeLogging=true als Parameter zu Ihrer Website-URL hinzufügen. Alternativ können Sie die einfache oder die benutzerdefinierte Protokollierung aktivieren. Einen zentralen Überblick über alle Plattformen finden Sie unter Ausführliche Protokollierung.

Einfache Protokollierung

• vor der initialisierung
• nach der initialisierung

1

enableLogging: true

1
2
3
4
5

braze.initialize('API-KEY', {
    baseUrl: 'API-ENDPOINT',
    enableLogging: true
});
braze.openSession();

1
2
3
4
5
6

braze.initialize('API-KEY', {
    baseUrl: 'API-ENDPOINT',
});
braze.openSession();
...
braze.toggleLogging();

Wichtig

Einfache Protokolle sind für alle Nutzer:innen sichtbar. Deaktivieren Sie sie daher oder wechseln Sie zu setLogger, bevor Sie Ihren Code in die Produktionsumgebung überführen.

Benutzerdefinierte Protokollierung

Verwenden Sie setLogger, um benutzerdefinierte Debugging-Nachrichten in der JavaScript-Konsole zu protokollieren. Im Gegensatz zu einfachen Protokollen sind diese Protokolle für Nutzer:innen nicht sichtbar.

1

setLogger(loggerFunction: (message: STRING) => void): void

Ersetzen Sie STRING durch Ihre Nachricht als einzelnen String-Parameter. Ihre Methode sollte in etwa so aussehen:

1
2
3
4
5

braze.initialize('API-KEY');
braze.setLogger(function(message) {
    console.log("Braze Custom Logger: " + message);
});
braze.openSession();

Upgrade des SDK

Hinweis

Diese Anleitung verwendet Codebeispiele aus dem Braze Web SDK 4.0.0+. Um ein Upgrade auf die neueste Web SDK-Version durchzuführen, siehe SDK Upgrade Guide.

Wenn Sie das Braze Internet-SDK über unser Content Delivery Network referenzieren, z. B. https://js.appboycdn.com/web-sdk/a.a/braze.min.js (wie in unseren standardmäßigen Integrationsanweisungen empfohlen), erhalten Ihre Nutzer:innen kleinere Updates (Fehlerbehebungen und abwärtskompatible Features, in diesem Beispiel die Versionen a.a.a bis a.a.z) automatisch, wenn sie Ihre Website aktualisieren.

Wenn wir jedoch größere Änderungen veröffentlichen, müssen Sie das Braze Internet-SDK manuell aktualisieren, um sicherzustellen, dass Breaking Changes Ihre Integration nicht beeinträchtigen. Darüber hinaus erhalten Sie keine automatischen Versionsupdates, wenn Sie unser SDK herunterladen und selbst hosten. In diesem Fall sollten Sie manuell aktualisieren, um die neuesten Features und Fehlerbehebungen zu erhalten.

Sie können sich über unsere neuesten Releases auf dem Laufenden halten, indem Sie unseren Release-Feed verfolgen – mit dem RSS-Reader oder Dienst Ihrer Wahl – und unser Changelog einsehen, um eine vollständige Übersicht über unseren Internet-SDK-Release-Verlauf zu erhalten. So aktualisieren Sie das Braze Internet-SDK:

• Aktualisieren Sie die Version der Braze-Bibliothek, indem Sie die Versionsnummer von https://js.appboycdn.com/web-sdk/[OLD VERSION NUMBER]/braze.min.js ändern – oder in den Abhängigkeiten Ihres Paketmanagers.
• Wenn Sie Web-Push integriert haben, aktualisieren Sie die Service-Worker-Datei auf Ihrer Website. Standardmäßig befindet sich diese unter /service-worker.js im Stammverzeichnis Ihrer Website, der Speicherort kann jedoch in einigen Integrationen angepasst sein. Sie müssen auf das Stammverzeichnis zugreifen, um eine Service-Worker-Datei zu hosten.

Sie müssen diese beiden Dateien koordiniert aktualisieren, um eine ordnungsgemäße Funktionalität sicherzustellen.

Andere Integrationsmethoden

Accelerated Mobile Pages (AMP)

1

<script async custom-element="amp-web-push" src="https://cdn.ampproject.org/v0/amp-web-push-0.1.js"></script>

1
2
3
4
5
6
7
8
9

<!-- A subscription widget -->
<amp-web-push-widget visibility="unsubscribed" layout="fixed" width="250" height="80">
  <button on="tap:amp-web-push.subscribe">Subscribe to Notifications</button>
</amp-web-push-widget>

<!-- An unsubscription widget -->
<amp-web-push-widget visibility="subscribed" layout="fixed" width="250" height="80">
  <button on="tap:amp-web-push.unsubscribe">Unsubscribe from Notifications</button>
</amp-web-push-widget>

1
2
3
4
5
6
7

<amp-web-push
layout="nodisplay"
id="amp-web-push"
helper-iframe-url="FILE_PATH_TO_YOUR_HELPER_IFRAME"
permission-dialog-url="FILE_PATH_TO_YOUR_PERMISSION_DIALOG"
service-worker-url="FILE_PATH_TO_YOUR_SERVICE_WORKER?apiKey={YOUR_API_KEY}&baseUrl={YOUR_BASE_URL}"
>

Asynchronous Module Definition (AMD)

Unterstützung deaktivieren

Wenn Ihre Website RequireJS oder einen anderen AMD-Modul-Loader verwendet, Sie das Braze Internet-SDK aber lieber über eine der anderen Optionen in dieser Liste laden möchten, können Sie eine Version der Bibliothek laden, die keine AMD-Unterstützung enthält. Diese Version der Bibliothek kann vom folgenden CDN-Standort geladen werden:

Modul-Loader

Wenn Sie RequireJS oder andere AMD-Modul-Loader verwenden, empfehlen wir, eine Kopie unserer Bibliothek selbst zu hosten und sie wie andere Ressourcen zu referenzieren:

1
2
3
4
5
6

require(['path/to/braze.min.js'], function(braze) {
  braze.initialize('YOUR-API-KEY-HERE', { baseUrl: 'YOUR-SDK-ENDPOINT' });
  // Required if you want in-app messages to display automatically
  braze.automaticallyShowInAppMessages();
  braze.openSession();
});

Electron

Electron unterstützt Web-Push-Benachrichtigungen nicht offiziell (siehe: dieses GitHub Issue). Es gibt andere Open-Source-Workarounds, die Sie ausprobieren können, die jedoch nicht von Braze getestet wurden.

Jest-Framework

Bei Verwendung von Jest wird möglicherweise ein Fehler wie SyntaxError: Unexpected token 'export' angezeigt. Um dies zu beheben, passen Sie Ihre Konfiguration in package.json an, damit das Braze SDK ignoriert wird:

1
2
3
4
5

"jest": {
  "transformIgnorePatterns": [
    "/node_modules/(?!@braze)"
  ]
}

SSR-Frameworks

Das Internet-SDK wird in einer Browser-Umgebung ausgeführt. In SSR-Frameworks initialisieren Sie Braze in einer Client-Only-Komponente, damit Ihr Server niemals SDK-Code ausführt.

Framework-unabhängiger dynamischer Import

Wenn Ihr Framework in diesem Abschnitt nicht aufgeführt ist, können Sie Braze dynamisch aus einem Client-Only-Lifecycle-Hook importieren.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// MyComponent/braze-exports.js
// Export the parts of the SDK that you need.
export { initialize, openSession } from "@braze/web-sdk";

// MyComponent/MyComponent.js
useEffect(() => {
    import("./braze-exports.js").then(({ initialize, openSession }) => {
        initialize("YOUR-API-KEY-HERE", {
            baseUrl: "YOUR-SDK-ENDPOINT",
            enableLogging: true,
        });
        openSession();
    });
}, []);

Wenn Sie webpack verwenden, können Sie dynamisch nur bestimmte SDK-Exporte importieren.

1
2
3
4
5
6
7
8
9
10
11
12
13

// MyComponent.js
useEffect(() => {
    import(
        /* webpackExports: ["initialize", "openSession"] */
        "@braze/web-sdk"
    ).then(({ initialize, openSession }) => {
        initialize("YOUR-API-KEY-HERE", {
            baseUrl: "YOUR-SDK-ENDPOINT",
            enableLogging: true,
        });
        openSession();
    });
}, []);

Gemeinsamer Hook für Next.js und Remix

Erstellen Sie einen wiederverwendbaren useBraze-Hook und rufen Sie ihn in der Nähe Ihres App-Roots auf.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

// hooks/useBraze.ts
import { useEffect, useRef } from "react";

export function useBraze() {
  const didInit = useRef(false);

  useEffect(() => {
    if (didInit.current) {
      return;
    }
    didInit.current = true;

    import("@braze/web-sdk")
      .then((braze) => {
        const initialized = braze.initialize("YOUR-API-KEY-HERE", {
          // Use your Braze Web SDK endpoint, such as sdk.iad-01.braze.com.
          baseUrl: "YOUR-SDK-ENDPOINT",
          enableLogging: false,
        });
        if (!initialized) {
          return;
        }

        // Optional: Identify signed-in users before opening a session.
        // braze.changeUser("external-id");

        // Optional: Automatically display in-app messages.
        // braze.automaticallyShowInAppMessages();
        braze.openSession();
      })
      .catch((error) => {
        console.error("Unable to load Braze SDK:", error);
      });
  }, []);
}

Next.js (App Router)

Rufen Sie useBraze in einer Client-Komponente auf, die Ihre App umschließt.

1
2
3
4
5
6
7
8
9
10

// app/components/AppRoot.tsx
"use client";

import type { ReactNode } from "react";
import { useBraze } from "../hooks/useBraze";

export function AppRoot({ children }: { children: ReactNode }) {
  useBraze();
  return <>{children}</>;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// app/layout.tsx
import type { ReactNode } from "react";
import { AppRoot } from "./components/AppRoot";

export default function RootLayout({
  children,
}: {
  children: ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <AppRoot>{children}</AppRoot>
      </body>
    </html>
  );
}

Next.js (Pages Router)

Rufen Sie useBraze am Anfang Ihrer benutzerdefinierten App-Komponente auf.

1
2
3
4
5
6
7
8
9
10
11

// pages/_app.tsx
import type { AppProps } from "next/app";
import { useBraze } from "../hooks/useBraze";

export default function App({ Component, pageProps }: AppProps) {
  useBraze();

  return (
    <Component {...pageProps} />
  );
}

Remix

Rufen Sie useBraze am Anfang Ihrer Root-Route-Komponente auf.

Für lokale Remix-Validierungsbeispiele führen Sie PORT=4013 npm run dev aus.

1
2
3
4
5
6
7
8
9

// app/root.tsx
import { Outlet } from "@remix-run/react";
import { useBraze } from "./hooks/useBraze";

export default function App() {
  useBraze();

  return <Outlet />;
}

Ereignisse protokollieren und Nutzer:innen aktualisieren

Nachdem useBraze das SDK an Ihrem App-Root initialisiert hat, können andere Client-Komponenten Braze-Methoden aufrufen. Ein gängiges Muster ist der Aufruf innerhalb von Nutzeraktionen wie onClick oder onSubmit. Im Beispiel werden die SDK-Methoden innerhalb des Click-Handlers geladen, anstatt am Anfang der Datei. Dadurch bleibt das Internet-SDK außerhalb des Server-Codes und es wird nur das geladen, was diese Aktion benötigt. Der webpackExports-Kommentar teilt webpack mit, welche Methoden eingebunden werden sollen, sodass Ihr Bundle kleiner bleibt.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// app/components/BuyButton.tsx
"use client";

export function BuyButton() {
  const handleClick = async () => {
    const { logCustomEvent, logPurchase, getUser } = await import(
      /* webpackExports: ["logCustomEvent", "logPurchase", "getUser"] */
      "@braze/web-sdk"
    );

    getUser()?.setCustomUserAttribute("last_purchase_date", "2026-05-04");
    logCustomEvent("clicked_buy", { source: "product_page" });
    logPurchase("sku_123", 19.99, "USD");
  };

  return <button onClick={handleClick}>Buy</button>;
}

Dieses Beispiel zeigt eine BuyButton-Komponente, die Aktivitäten protokolliert, wenn jemand auf Kaufen klickt. Zuerst werden nur logCustomEvent, logPurchase und getUser zum Klick-Zeitpunkt importiert. Dann wird ein Nutzerattribut aktualisiert, ein angepasstes Event protokolliert und ein Kauf erfasst. Dieses Muster hilft Ihnen, die Initialisierung zentral in useBraze zu halten, während Sie gleichzeitig bedeutungsvolle Aktionen aus jeder Client-Komponente heraus tracken können.

Wenn Sie Remix mit Vite verwenden und package-root-Importe zur Laufzeit fehlschlagen, nutzen Sie den bestehenden Vite-Workaround. Weitere Informationen finden Sie unter Vite.

Eine vollständige Liste der verfügbaren Methoden finden Sie in der Braze JavaScript-Referenzdokumentation.

Tealium iQ

Tealium iQ bietet eine grundlegende schlüsselfertige Braze-Integration. Um die Integration zu konfigurieren, suchen Sie in der Tealium Tag Management-Oberfläche nach Braze und geben Sie den Internet-SDK-API-Schlüssel aus Ihrem Dashboard an.

Für weitere Details oder ausführliche Unterstützung bei der Tealium-Konfiguration lesen Sie unsere Integrationsdokumentation oder wenden Sie sich an Ihren Tealium Account Manager.

Vite

Wenn Sie Vite verwenden und eine Warnung zu zirkulären Abhängigkeiten oder Uncaught TypeError: Class extends value undefined is not a constructor or null sehen, müssen Sie das Braze SDK möglicherweise aus der Dependency Discovery ausschließen:

1
2
3

optimizeDeps: {
    exclude: ['@braze/web-sdk']
},

Andere Tag-Manager

Braze kann auch mit anderen Tag-Management-Lösungen kompatibel sein, indem Sie unsere Integrationsanweisungen innerhalb eines benutzerdefinierten HTML-Tags befolgen. Wenden Sie sich an eine Braze-Vertretung, wenn Sie Hilfe bei der Bewertung dieser Lösungen benötigen.