Initial SDK Setup

Integrating the Braze SDK will provide you with basic analytics functionality as well as in-app messages with which you can engage your users. Note that the web SDK file size is 32.3 KB.

Step 1: Integrate the Braze Library

To integrate the Braze Web SDK, simply follow the instructions in the “Getting Started” section of the Braze Web SDK Github Repository. Be sure to substitute the API key found within the “App Settings” page of the Braze dashboard for YOUR-API-KEY-HERE. For more detailed technical documentation, refer to the complete JSDocs.

If you have been provided a custom SDK endpoint, please include this in addition to your API key:

US Cluster:

appboy.initialize('YOUR-API-KEY-HERE', {baseUrl: 'https://customer.iad-03.braze.com/api/v3'})

EU Cluster:

appboy.initialize('YOUR-API-KEY-HERE', {baseUrl: 'https://customer.fra-01.braze.eu/api/v3'})

Error Logging

To enable logging, you can pass the option enableLogging: true to your initialize function (or call appboy.toggleAppboyLogging() after initialization), which will cause Braze to log to the javascript console. 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() before you release your page to production.

Tag Managers

Google Tag Manager

Initializing the SDK

Braze’s SDK can be initialized and controlled within tags configured from Google Tag Manager.

To initialize Braze’s SDK create a ‘Custom HTML’ tag within your Google Tag Manager workspace. Place Braze’s Web SDK/javascript code from the standard integration instructions within the tag.

This is instead of directly placing the snippit directly within the <head> section of your website.

On page load, include window.appboy = appboy; after appboy.openSession() near the end of the of the initialize tag. Subsequent tags which fire after page load can then reference this. For example <script type="text/javascript">window.appboy.logCustomEvent("test event")</script>.

GTM_initialize_snippit

Please also ensure to replace the API key and custom SDK endpoint in the code with your API key and, if applicable, custom endpoint.

Braze suggests the tag has the trigger configuration of Page View > DOM Ready. Other Page View triggers can fire the tag, provided that no other Braze related tags are fired to prior to this.

GTM_trigger_example

Logging Events and using Braze’s Messaging Channels

For Push, In-App Message, Newsfeed integration instructions please follow the standard integration instructions.

For Analytics integration, reference <script type="text/javascript">window.appboy.logCustomEvent("test event")</script> instead of re-using Braze’s Web SDK/javascript code.

GTM_tag_configuration

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. Please reach out to the Success Squad if you need help evaluating these solutions.

Upgrading The SDK

When you reference the Braze Web SDK from our content delivery network, for example https://js.appboycdn.com/web-sdk/a.a/appboy.min.js (as recommended by our default integration instructions), your users will receive minor updates (bug fixes and backwards 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 insure that nothing in your integration will be impacted by any breaking changes. Additionally, if you download our SDK and rehost it yourself (which is also a valid integration path), you won’t receive any version updates automatically and should upgrade manually from time-to-time 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 JavaScript file - in the default integration, this means changing the version number of https://js.appboycdn.com/web-sdk/[OLD VERSION NUMBER]/appboy.min.js in the <head> of your site to https://js.appboycdn.com/web-sdk/[NEW VERSION NUMBER]/appboy.min.js
  • 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 of your site, but the location may be customized in some integrations.

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

WAS THIS PAGE HELPFUL?