Über das Web Braze SDK

Das Web Braze SDK ermöglicht es Ihnen, Analytics zu erfassen und Ihren Web-Nutzer:innen umfangreiche In-App Messages, Push-Benachrichtigungen und Content Cards 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 Web SDK integrieren

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

• Code-basierte Integration: Integrieren Sie das Web Braze SDK 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 Web Braze SDK 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 NPM-Integrationsmethode. Zu den Vorteilen gehören das lokale Speichern von SDK-Bibliotheken auf Ihrer Website, die Immunität gegenüber Ad-Blocker-Erweiterungen und schnellere Ladezeiten als Teil der Bundler-Unterstützung.

• code-basierte integration
• google tag manager

Schritt 1: Braze-Bibliothek installieren

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

Wichtig

Während die meisten Ad-Blocker das Braze Web SDK nicht blockieren, sind einige restriktivere Ad-Blocker dafür bekannt, Probleme zu verursachen.

• package manager
• braze cdn

Wenn 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 auf die übliche Weise 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 Web SDK direkt zu Ihrem HTML hinzu, indem Sie auf unser CDN-gehostetes Skript verweisen, das die Bibliothek asynchron lädt.

Wichtig

Die standardmäßige Einstellung Cross-Site-Tracking verhindern in Safari kann verhindern, dass In-App-Nachrichten-Typen wie Banner und Content Cards angezeigt werden, wenn Sie die CDN-Integrationsmethode verwenden. Um dieses Problem zu vermeiden, verwenden Sie die NPM-Integrationsmethode, damit Safari diese Nachrichten nicht als Cross-Site-Traffic klassifiziert und Ihre Web-Nutzer:innen sie in allen unterstützten Browsern sehen können.

Schritt 2: Das SDK initialisieren

Nachdem das Braze Web SDK zu Ihrer Website hinzugefügt wurde, initialisieren Sie die Bibliothek mit dem API-Schlüssel und der SDK-Endpunkt-URL, die Sie unter Einstellungen > App-Einstellungen in Ihrem Braze-Dashboard 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 Web SDK-Anfragen werden nicht unterstützt: Die Web SDK baseUrl muss ein Braze SDK-Endpunkt sein (z. B. sdk.iad-05.braze.com). Braze unterstützt kein Routing von Web SDK-Traffic über eine kundeneigene Domain mittels CNAME-Einträgen. Wenn Sie möchten, dass Web 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. Wenn Sie die Nachrichtenanzeige manuell verwalten 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

Wenn Sie feststellen, dass Sitzungen fehlen, oder wenn Sie die Sitzung für Nutzer:innen, die auf Ihrer Website anonym bleiben, nicht tracken 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 die 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(), wenn Sie eine externe ID setzen).

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

Wichtig

Anonyme Nutzer:innen auf mobilen Geräten oder im Web können zu Ihren MAU gezählt werden. Daher möchten Sie möglicherweise das SDK bedingt laden oder 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.

Schritt 1: 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.

Schritt 2: 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.

Schritt 3: 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 Einstellungen > App-Einstellungen 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.

Schritt 4: 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.

Schritt 5: 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.

Schritt 6: 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 angepasste Protokollierung aktivieren. Eine zentralisierte Übersicht ü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. Erwägen Sie daher, sie zu deaktivieren, oder wechseln Sie zu setLogger, bevor Sie Ihren Code in die Produktion überführen.

Angepasste Protokollierung

Verwenden Sie setLogger, um angepasste Debugging-Nachrichten in der JavaScript-Konsole zu protokollieren. Im Gegensatz zu einfachen Protokollen sind diese Protokolle nicht für Nutzer:innen 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 Web SDK über unser Content Delivery Network referenzieren, z. B. https://js.appboycdn.com/web-sdk/a.a/braze.min.js (wie in unseren Standard-Integrationsanweisungen empfohlen), erhalten Ihre Nutzer:innen automatisch kleinere Updates (Fehlerbehebungen und abwärtskompatible Features, in diesem Beispiel die Versionen a.a.a bis a.a.z), wenn sie Ihre Website aktualisieren.

Wenn wir jedoch größere Änderungen veröffentlichen, müssen Sie das Braze Web SDK manuell upgraden, um sicherzustellen, dass Breaking Changes Ihre Integration nicht beeinträchtigen. Wenn Sie unser SDK herunterladen und selbst hosten, erhalten Sie außerdem keine automatischen Versionsupdates und sollten manuell upgraden, 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 abonnieren – mit dem RSS-Reader oder Dienst Ihrer Wahl – und in unserem Changelog eine vollständige Übersicht über die Release-Historie unseres Web SDK einsehen. So upgraden Sie das Braze Web 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 die Abhängigkeiten in Ihrem Paketmanager anpassen.
• 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 bei einigen Integrationen angepasst worden sein. Sie müssen auf das Stammverzeichnis zugreifen können, um eine Service-Worker-Datei zu hosten.

Diese beiden Dateien müssen koordiniert aktualisiert werden, um die 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-Modullader verwendet, Sie das Braze Web 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:

Modullader

Wenn Sie RequireJS oder andere AMD-Modullader 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 weitere Open-Source-Workarounds, die Sie ausprobieren können, die jedoch nicht von Braze getestet wurden.

Jest-Framework

Bei der Verwendung von Jest kann ein Fehler ähnlich wie SyntaxError: Unexpected token 'export' auftreten. Um diesen zu beheben, passen Sie Ihre Konfiguration in package.json an, um das Braze SDK zu ignorieren:

1
2
3
4
5

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

SSR-Frameworks

Das Web SDK wird in einer Browserumgebung ausgeführt. In SSR-Frameworks initialisieren Sie Braze in einer rein clientseitigen Komponente, damit Ihr Server niemals SDK-Code ausführt.

Framework-unabhängiger dynamischer Import

Wenn Ihr Framework nicht in diesem Abschnitt aufgeführt ist, können Sie Braze dynamisch aus einem rein clientseitigen 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 angepassten 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 in Ihrem App-Root initialisiert hat, können andere Client-Komponenten Braze-Methoden aufrufen. Ein gängiges Muster ist der Aufruf innerhalb von Nutzer:innen-Aktionen, wie onClick oder onSubmit. Im Beispiel werden die SDK-Methoden innerhalb des Click-Handlers geladen, anstatt am Anfang der Datei. Dadurch bleibt das Web SDK aus dem Servercode heraus, und es wird nur das geladen, was die jeweilige Aktion benötigt. Der webpackExports-Kommentar teilt Webpack mit, welche Methoden eingebunden werden sollen, damit 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 Buy klickt. Zunächst werden nur logCustomEvent, logPurchase und getUser zum Zeitpunkt des Klicks importiert. Dann wird ein Nutzer:innen-Attribut aktualisiert, ein angepasstes Event protokolliert und ein Kauf erfasst. Dieses Muster hilft Ihnen, die Initialisierung zentral in useBraze zu halten und gleichzeitig aussagekräftige Aktionen von jeder Client-Komponente aus zu verfolgen.

Wenn Sie Remix mit Vite verwenden und Paketroot-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 einfache schlüsselfertige Braze-Integration. Um die Integration zu konfigurieren, suchen Sie in der Tealium Tag-Management-Oberfläche nach Braze und geben Sie den Web SDK-API-Schlüssel aus Ihrem Dashboard an.

Weitere Details oder ausführliche Unterstützung bei der Tealium-Konfiguration finden Sie in unserer 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 erhalten, müssen Sie möglicherweise das Braze SDK von der Abhängigkeitserkennung ausschließen:

1
2
3

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

Andere Tag-Manager

Braze ist möglicherweise auch mit anderen Tag-Management-Lösungen kompatibel, wenn Sie unsere Integrationsanweisungen innerhalb eines angepassten HTML-Tags befolgen. Wenden Sie sich an eine Braze-Vertretung, wenn Sie Hilfe bei der Evaluierung dieser Lösungen benötigen.