Über das Web Braze SDK

Mit dem Web Braze SDK können Sie Analytics erfassen und Ihren Web-Nutzer:innen umfangreiche In-App-Nachrichten, Push-Benachrichtigungen und Content-Card-Nachrichten anzeigen. 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.

Web SDK integrieren

Sie können das Web Braze SDK mithilfe der folgenden Methoden integrieren. Weitere Optionen finden Sie unter anderen Integrationsmethoden.

• Code-basierte Integration: Führen Sie die Integration des Web Braze SDK direkt in Ihre Codebasis durch, indem Sie Ihren bevorzugten Paketmanager oder das Braze CDN verwenden. Dadurch erhalten Sie die vollständige Kontrolle darüber, wie das SDK geladen und konfiguriert wird.
• Google Tag Manager: Eine No-Code-Lösung, mit der Sie die Integration des Web Braze SDK durchführen 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, die Immunität gegenüber Ad-Blocker-Erweiterungen und die Verkürzung der Ladezeiten im Rahmen der Bundler-Unterstützung.

• code-based integration
• google tag manager

1. Schritt: Installieren Sie die Braze-Bibliothek

Sie können die Braze-Bibliothek mit einer der folgenden Methoden installieren. Sollte Ihre Website jedoch eine Content-Security-Policy verwenden, überprüfen Sie bitte die Content Security Policy, bevor Sie fortfahren.

Wichtig

Während die meisten Werbeblocker das Braze Web SDK nicht blockieren, ist bekannt, dass einige restriktivere Werbeblocker Probleme verursachen können.

• package manager
• braze cdn

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

Ab v3.0.0 sind nun auch Typescript-Definitionen 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 mittels import oder require verwenden:

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 in den HTML-Code ein, indem Sie auf das auf unserem CDN gehostete Skript verweisen, das die Bibliothek asynchron lädt.

Wichtig

Die Standard-Einstellung Cross-Site-Tracking verhindern in Safari kann dazu führen, dass In-App-Nachrichtentypen wie Banner und Content Cards nicht angezeigt werden, wenn Sie die CDN-Integrationsmethode verwenden. Um dieses Problem zu vermeiden, empfehlen wir die Verwendung der NPM-Integrationsmethode, damit Safari diese Nachrichten nicht als Cross-Site-Traffic einstuft und Ihre Nutzer:innen sie in allen unterstützten Webbrowsern sehen können.

2. Schritt: Initialisieren Sie das SDK

Nachdem Sie das Braze Web SDK zu Ihrer Website hinzugefügt haben, initialisieren Sie die Bibliothek mit dem API-Schlüssel und der SDK-Endpunkt-URL, die Sie in Ihrem Braze-Dashboard unter Einstellungen > App-Einstellungen finden. Eine vollständige Liste der Optionen für braze.initialize() sowie unsere anderen 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 (zum Beispiel sdk.iad-05.braze.com). Braze unterstützt nicht die Weiterleitung von Web-SDK-Datenverkehr über CNAME-Einträge durch eine kundeneigene Domain. Sollten Sie Web-SDK-Anfragen von Ihrer eigenen Domain aus senden müssen, wenden Sie sich bitte 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 Anzeige von Nachrichten manuell verwalten möchten, entfernen Sie diesen Aufruf und verwenden Sie stattdessen braze.subscribeToInAppMessage(). Weitere Informationen finden Sie unter Zustellung von In-App-Nachrichten.

Fehlerbehebung bei fehlenden Sitzungen für anonyme Nutzer:innen

Wenn Sie das Verhalten „Sitzung fehlt“ beobachten oder das Tracking der Sitzung für Nutzer:innen, die im Web anonym bleiben, nicht durchführen können, stellen Sie sicher, dass Ihre Integration während der Initialisierung braze.openSession() aufruft.

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

Weitere Informationen finden Sie in Schritt 2: Initialisieren Sie das SDK.

Wichtig

Anonyme Nutzer:innen auf Mobil- oder Webgeräten können zu Ihrer MAU gezählt werden. Vielleicht möchten Sie das SDK deshalb lieber bedingt laden oder initialisieren, um diese Nutzer:innen von der 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-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.

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.

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 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 in die URL Ihrer Website einfügen. Alternativ können Sie auch die einfache oder angepasste Protokollierung aktivieren. Für eine zentralisierte Übersicht über alle Plattformen hinweg siehe Ausführliche Protokollierung.

Grundlegende Protokollierung

• before initialization
• after initialization

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

Die Basisprotokolle sind für alle Nutzer:innen sichtbar. Daher sollten Sie diese Funktion deaktivieren oder zu setLogger wechseln, bevor Sie Ihren Code für die Produktionsumgebung freigeben.

Angepasste Protokollierung

Verwenden Sie setLogger, um angepasste Debugging-Nachrichten in der JavaScript-Konsole zu protokollieren. Im Gegensatz zu den Basisprotokollen sind diese Protokolle für die 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 wie die folgende:

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

Upgraden 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 aus unserem Content Delivery Network referenzieren, zum Beispiel 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, Versionen a.a.a bis a.a.z in den obigen Beispielen), wenn sie Ihre Website aktualisieren.

Bei der Veröffentlichung größerer Änderungen bitten wir Sie jedoch, das Braze Web SDK manuell zu upgraden, um sicherzustellen, dass sich grundlegende Änderungen nicht auf Ihre Integration auswirken. Wenn Sie unser SDK herunterladen und selbst hosten, erhalten Sie keine automatischen Updates und müssen manuell upgraden, um die neuesten Features und Fehlerbehebungen zu erhalten.

Um auf dem aktuellen Stand zu bleiben, empfehlen wir Ihnen, mit dem RSS-Reader oder einem anderen Dienst Ihrer Wahl unseren Release-Feed zu abonnieren. Einen vollständigen Überblick über die Release-Historie unseres Web SDK finden Sie in unserem Changelog. So führen Sie ein Upgrade des Braze Web SDK durch:

• 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 Datei unter /service-worker.js im Stammverzeichnis Ihrer Website, aber der Speicherort kann bei einigen Integrationen angepasst werden. Sie müssen auf das Stammverzeichnis zugreifen, um eine Service-Worker-Datei zu hosten.

Bitte führen Sie ein Update für diese beiden Dateien in Abstimmung miteinander durch, um eine ordnungsgemäße Funktionalität zu gewährleisten.

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}"
>

Asynchrone Moduldefinition (AMD)

Unterstützung deaktivieren

Falls Ihre Website RequireJS oder einen anderen AMD-Modul-Loader verwendet, Sie jedoch das Braze Web SDK 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 Ihnen, selbst eine Kopie unserer Bibliothek zu hosten und genauso auf sie zu verweisen, wie Sie es mit anderen Ressourcen tun würden:

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 offiziell keine Web-Push-Benachrichtigungen (siehe dieses GitHub-Issue). Es gibt andere Open-Source-Workarounds, die Sie ausprobieren können, die aber nicht von Braze getestet wurden.

Jest-Framework

Bei der Verwendung von Jest wird möglicherweise eine Fehlermeldung ähnlich SyntaxError: Unexpected token 'export' angezeigt. Passen Sie für die Fehlerbehebung Ihre Konfiguration in package.json so an, dass das Braze SDK ignoriert wird:

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 Client-only-Komponente, damit Ihr Server niemals SDK-Code ausführt.

Framework-agnostischer 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 nur bestimmte SDK-Exporte dynamisch 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 an Ihrem App-Root initialisiert hat, können andere Client-Komponenten Braze-Methoden aufrufen. Ein gängiges Muster besteht darin, sie innerhalb von Nutzeraktionen wie onClick oder onSubmit aufzurufen. Im Beispiel werden die SDK-Methoden innerhalb des Click-Handlers geladen, anstatt am Anfang der Datei. Dadurch bleibt das Web SDK aus dem Server-Code heraus und es wird nur das geladen, was diese Aktion benötigt. Der webpackExports-Kommentar teilt Webpack mit, welche Methoden einbezogen 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 Buy klickt. Zunächst werden nur logCustomEvent, logPurchase und getUser zum Zeitpunkt des Klicks importiert. Dann wird ein Nutzerattribut aktualisiert, ein angepasstes Event protokolliert und ein Kauf protokolliert. Dieses Muster hilft Ihnen, die Initialisierung in useBraze zentralisiert zu halten, während Sie dennoch sinnvolle 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 einfache, schlüsselfertige Braze-Integration. Um die Integration zu konfigurieren, suchen Sie in der Tealium Tag-Management-Schnittstelle nach Braze und geben Sie den Web-SDK-API-Schlüssel von Ihrem Dashboard an.

Für weitere Informationen oder umfassende Unterstützung bei der Konfiguration von Tealium empfehlen wir Ihnen, unsere Integrationsdokumentation zu konsultieren oder sich an Ihren Tealium-Account-Manager zu wenden.

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 von der Abhängigkeitserkennung ausschließen:

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

Andere Tag-Manager

Braze kann auch mit anderen Tag-Management-Lösungen kompatibel sein. Folgen Sie dazu unseren Integrationsanweisungen innerhalb eines angepassten HTML-Tags. Bitte wenden Sie sich an eine Braze-Vertretung, wenn Sie Unterstützung bei der Bewertung dieser Lösungen benötigen.