Initial SDK setup

The Braze Web SDK lets you collect analytics and display rich In-App Messages, Push, and Content Card messages to your web users.

For a complete technical reference, please see our JavaScript Documentation.

Step 1: Install the Braze library

There are three easy ways to integrate the Web SDK, to include analytics and messaging components on your site. Be sure to view our Push Integration Guide if you plan to use Web Push features.

If your website uses a Content-Security-Policy, then please follow our CSP Header Guide in addition to the integration steps below.

Option 1: NPM or Yarn

If your site uses NPM or Yarn package managers, you can add the Braze NPM package as a dependency.

Typescript definitions are now included as of v3.0.0 🎉. For notes on upgrading from 2.x to 3.x, please see our Changelog.

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

Once installed, you can import or require the library in the typical fashion:

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

Option 2: Google tag manager

The Braze Web SDK can be quickly installed from the Google Tag Manager Template Library. Two tags are supported:

  1. Initialization Tag - loads the Web SDK onto your website, and optionally sets the External User ID

  2. Actions Tag - used to trigger custom events, purchases, change user IDs, or stop/resume SDK tracking

For more information, please see the Google Tag Manager Integration Guide.

Option 3: Braze CDN

Add the Braze Web SDK directly to your HTML by referencing our CDN-hosted script to load the library asynchronously.

The CDN integration code can be found on our Github Repo.

Step 2: Initialize Braze

Once the Braze Web SDK is added to your website, initialize the library with the API Key and SDK Endpoint URL found in Manage Settings > Settings within your Braze dashboard.

Note: If you’ve configured your Braze initialization options in a Tag Manager, you can skip this step.

For a complete list of options for appboy.initialize() please see our JavaScript Documentation.

// initialize the SDK
appboy.initialize('YOUR-API-KEY-HERE', {

// optionally show all In-App Messages without custom handling

// optionally set the current user's External ID
if (isLoggedIn){

// start (or continue) a session

For all other JavaScript methods, please see our complete JavaScript Reference Documentation.

Step 3: Web push (optional)

To use Web Push Notifications, additional setup is required.

Please see our Push Notifications section for instructions.


To assist in troubleshooting, you can enable verbose logging in the SDK. This is useful for development but is visible to all users, so you should remove this option or provide an alternate logger with appboy.setLogger() in your production environment.

appboy.initialize("YOUR-API-KEY-HERE", {
    baseUrl: "",
    enableLogging: true

// or, after initialization:


Upgrading the SDK

When you reference the Braze Web SDK from our content delivery network, for example, (as recommended by our default integration instructions), your users will receive minor updates (bug fixes and backward compatible features, versions a.a.a through a.a.z in the above examples) automatically when they refresh your site.

When we release major changes however, we require you to upgrade the Braze Web SDK manually to ensure that nothing in your integration will be impacted by any breaking changes. Additionally, if you download our SDK and host it yourself, you won’t receive any version updates automatically and should upgrade manually to receive the latest features and bug fixes.

You can keep up-to-date with our latest release following our release feed with the RSS Reader or service of your choice, and see our changelog for a full accounting of our Web SDK release history. To upgrade the Braze Web SDK:

  • Update the Braze library version by changing the version number of[OLD VERSION NUMBER]/appboy.min.js, or in your package manager’s dependencies.
  • If you have web push integrated, update the service worker file on your site - by default, this is located at /service-worker.js at the root directory of your site, but the location may be customized in some integrations. Please note that you must be able to access the root directory to host a service worker file.

These two files must be updated in coordination with each other to ensure proper functionality.

Alternative integration methods

AMD module loader

If you are using Google Tag Manager alongside an AMD module loader such as RequireJS to load Braze’s SDK you will need to use the RequireJS-compatible integration snippet in your <head> tag.

For further instruction on this please see the appropriate section of our Braze Web SDK Github Repository.

Tealium iQ

Tealium iQ offers a basic turnkey Braze integration. To configure the integration, just search for Braze in the Tealium Tag Management interface, and provide the Web SDK API key from your dashboard.

For more details, or in-depth Tealium configuration support, check out our integration documentation or reach out to your Tealium Account Manager.

Other tag managers

Braze may also be compatible with other tag management solutions by following our integration instructions within a custom HTML tag. Please reach out to a Braze representative if you need help evaluating these solutions.

New Stuff!