By default, the Braze Web SDK ignores activity from known spiders or web crawlers, such as Google, based on the user agent string. This saves data points, makes analytics more accurate, and may improve page rank. However, if you want Braze to log activity from these crawlers instead, you may set this option to true.
By default, the Braze Web SDK does not allow user-supplied Javascript click actions, as it allows Braze dashboard
users to run Javascript on your site. To indicate that you trust the Braze dashboard users to write non-malicious
Javascript click actions, set this property to true. If enableHtmlInAppMessages is true, this option will also be
set to true.
If you provide a value for this option, user events sent to Braze will be associated with the given version, which can be used for user segmentation.
This option is required to configure the Braze Web SDK to use the appropriate endpoint for your integration - for example:
appboy.initialize('YOUR-API-KEY-HERE', { baseUrl: 'sdk.iad-03.appboy.com' })If you provide a value for this option, the Braze SDK will add the nonce to any <script> and <style> elements created by
the SDK. This can be used to permit the Braze SDK to work with your website's Content Security Policy.
Note that in addition to setting this nonce, you may also need to allow FontAwesome to load, which you can do by either adding
use.fontawesome.com to your Content Security Policy allowlist or by using the doNotLoadFontAwesome option and loading it manually.
By default, the Braze SDK automatically detects and collects all device properties in DeviceProperties. To override
this behavior, provide an array of DeviceProperties. To disable all properties being sent to Braze servers, provide
an empty array. Note that without some properties, not all features will function properly. For instance, without the time
zone, local timezone delivery will not function.
By default, users who have already granted web push permission (e.g. through appboy.registerAppboyPushMessages or from
a prior push provider) will sync their push token with the Braze backend automatically on new session to ensure deliverability.
To disable this behavior, set this option to true.
Braze uses Font Awesome for in-app message icons. By default, Braze will automatically load
FontAwesome 4.7.0 from the FontAwesome CDN. To disable this behavior (e.g. because your site uses a customized version
of FontAwesome), set this option to true. Note that if you do this, you are responsible for ensuring that FontAwesome
is loaded on your site - otherwise in-app messages may not render correctly.
By default, the Braze Web SDK does not enable HTML in-app messages, as they allow Braze dashboard users to run Javascript
on your site. To indicate that you trust the Braze dashboard users to write non-malicious HTML in-app messages, set this
property to true. If allowUserSuppliedJavascript is set to true, this option will also be set to true.
Set to true to enable logging by default. Note that this will cause Braze to log to the javascript console, which is visible
to all users! You should probably remove this or provide an alternate logger with appboy.setLogger before you release
your page to production.
Set to true to enable the SDK Authentication feature. For more information about SDK Authentication, see our Product Documentation.
By default, the Braze SDK will show In-App Messages with a z-index of 1040 for the screen overlay, 1050 for the actual in-app message,
and 1060 for the message's close button. Provide a value for this option to override these default z-indexes. The value provided
will be used for the backdrop, value + 1 will be used for the in-app message, and value + 2 will be used for the close button.
By default, any SDK-generated user-visible messages will be displayed in the user's browser language. Provide a value for this
option to override that behavior and force a specific language. The value for this option should be a
ISO 639-1 Language Code. If a desired localization is not available,
the SDK will default to English. See also User.setLanguage for setting the language you use within the Braze dashboard to
localize your own messaging content.
By default, appboy.registerAppboyPushMessages/appboy.unregisterAppboyPushMessages assume that they control and can
register and unregister the site's service worker. If you have your own service worker that you register and control the
lifecycle of, set this option to true and the Braze SDK will not register or unregister a service worker. If you set this
option to true, in order for push to function correctly you must register the service worker yourself BEFORE calling
appboy.registerAppboyPushMessages, and ensure that it contains Braze's service worker code, either with
self.importScripts('https://js.appboycdn.com/web-sdk-develop/3.3/service-worker.js'); or by including the content
of that file directly. When this option is true, the serviceWorkerLocation option is irrelevant and is ignored.
By default, a trigger action will only fire if at least 30 seconds have elapsed since the last trigger action. Provide a value for this configuration option to override that default with a value of your own. We do not recommend making this value any smaller than 10 to avoid spamming the user with notifications.
By default, the Braze SDK will store small amounts of data (user ids, session ids), in cookies. This is done to allow Braze
to recognize users and sessions across different subdomains of your site. If this presents a problem for you, pass true
for this option to disable cookie storage and rely entirely on HTML 5 localStorage to identify users and sessions. The downside
of this configuration is that you will be unable to recognize users across subdomains of your site.
By default, links from Card objects load in the current tab or window. Set this option to true to make links from
cards open in a new tab or window.
By default, links from in-app message clicks load in the current tab or a new tab as specified in the dashboard on a
message-by-message basis. Set this option to true to force all links from in-app message clicks open in a new tab or window.
By default, when an in-app message is showing, pressing the escape button or a click on the greyed-out background of the
page will dismiss the message. Set this option to true to prevent this behavior and require an explicit button click
to dismiss messages.
If you support Safari push, you must specify this option with the website push ID that you provided to Apple when creating your Safari push certificate (starts with "web", e.g. "web.com.example.domain").
By default, when registering users for web push notifications Braze will look for the required service worker file in the
root directory of your web server at /service-worker.js. If you want to host your service worker at a different path
on that server, provide a value for this option that is the absolute path to the file, e.g. /mycustompath/my-worker.js.
VERY IMPORTANT: setting a value here limits the scope of push notifications on your site. For instance, in the above
example, because the service worker file is located within the /mycustompath/ directory, appboy.registerAppboyPushMessages
MAY ONLY BE CALLED from web pages that start with http://yoursite.com/mycustompath/.
By default, sessions time out after 30 minutes of inactivity. Provide a value for this configuration option to override that default with a value of your own.
When a user first uses Braze on a device they are considered "anonymous". Use this method to identify a user with a unique ID, which enables the following:
When you request a user switch (which is any call to changeUser where the new user ID is not the same as the existing user ID), the current session for the previous user (anonymous or not) is automatically ended and a new session is started. Similarly, following a call to changeUser, any events which fire are guaranteed to be for the new user -- if an in-flight server request completes for the old user after the user switch no events will fire, so you do not need to worry about filtering out events from Braze for old users.
Additionally, if you identify a user which has never been identified on another device, the entire history of that user as an "anonymous" user on this device will be preserved and associated with the newly identified user. However, if you identify a user which has been identified in another app, any history which was already flushed to the server for the anonymous user on this device will become orphaned and will not be associated with any future users. These orphaned users are not considered in your user counts and will not be messaged.
Note: Once you identify a user, you cannot revert to the "anonymous" user. The transition from anonymous to identified tracking is only allowed once because the initial anonymous user receives special treatment to allow for preservation of their history. As a result, we recommend against changing the user ID just because your app has entered a "logged out" state because it makes you unable to target the previously logged out user with re-engagement campaigns. If you anticipate multiple users on the same device, but only want to target one of them when your app is in a logged out state, we recommend separately keeping track of the user ID you want to target while logged out and switching back to that user ID as part of your app's logout process.
A unique identifier for this user. Limit 997 bytes.
An encrypted signature to be used to authenticate the current user. You can update the signature
using the setSdkAuthenticationSignature method. This signature will only have an effect if the enableSdkAuthentication
initialization option is set to true.
Destroys this appboy instance, destroying all subscription callbacks and releasing member variables which retain memory.
Get all currently available cards from the last content cards refresh.
ContentCards object which includes all currently available
Card objects from the last content cards refresh.Asynchronously retrieves the 'device id,' a randomly generated ID that is stored on the browser. This ID resets for private browsing sessions and when website data is cleared. For example:
appboy.getDeviceId(function(deviceId) {
console.log('The device id is ' + deviceId);
});Asynchronous callback - this will be invoked with the deviceId.
Initializes this appboy instance with your API key. This method must be called before other Braze methods are
invoked, and is part of the default loading snippets. Subsequent calls will be ignored until 'destroy`
is called.
Your app's Braze API Key. Your API keys can be found here.
Configuration options. See InitializationOptions for supported options.
appboy instance has been successfully initialized.
Reasons for returning false include a missing API key/base URL, user opt out, and ignored crawler bot activity.Whether or not the user has blocked push. If the user has blocked push, they cannot be prompted to register again, and must manually remove the block in order to receive push.
DEPRECATED - Tests whether the user has given this browser push permission (they may still be unsubscribed from
push via User.setPushNotificationSubscriptionType). A true value essentially means that
appboy.registerAppboyPushMessages may be called without the user being prompted. Useful for migrating existing
non-Braze push registrations to appboy.
Invoked if the user has granted push access on this browser
Invoked if the user has not granted push access on this browser
Tests whether the user has given this browser push permission (they may still be unsubscribed from push via
User.setPushNotificationSubscriptionType). A true value essentially means that
appboy.registerAppboyPushMessages may be called without the
user being prompted. Useful for migrating existing non-Braze push registrations to appboy.
Whether or not the user has granted push permission. If this returns true,
appboy.registerAppboyPushMessages may be called without the user being prompted. If this returns false,
appboy.registerAppboyPushMessages may prompt the user (if appboy.isPushSupported returns true) or do
nothing (if appboy.isPushSupported returns false)
The W3C Push API is partially supported across the browser landscape. This method allows you to programmatically determine whether push is supported in the current browser, and whether to show push-related user class elements to the user.
Whether or not push is supported in this environment.
Logs that the user clicked the given card. This is done automatically when you use Appboy's display module and should only be called if you're bypassing that and manually building the DOM for displaying the cards in your own code.
the Card object that received a click
whether to log this as a content cards event (as opposed to the legacy news feed)
Whether or not the event was successfully logged (to be flushed later).
Logs that the user dismissed the given card. This is done automatically when you use Appboy's display module and should only be called if you're bypassing that and manually building the DOM for displaying the cards in your own code.
Whether or not the event was successfully logged (to be flushed later).
Logs that the user saw the given cards. This is done automatically when you use Appboy's display module and should only be called if you're bypassing that and manually building the DOM for displaying the cards in your own code.
array of Card objects that received impressions
whether to log this as a content cards event (as opposed to the legacy news feed)
Whether or not the event was successfully logged (to be flushed later).
Logs that the content cards were displayed. This is done automatically when you use Appboy's display module and should only be called if you're bypassing that and manually building the class for displaying the cards in your own code.
Reports that the current user performed a custom named event.
The identifier for the event to track. Best practice is to track generic events useful for segmenting, instead of specific user actions (i.e. track watched_sports_video instead of watched_video_adrian_peterson_td_mnf). Value is limited to 255 characters in length, cannot begin with a $, and can only contain alphanumeric characters and punctuation.
Hash of properties for this event. Keys are limited to 255 characters in length, cannot begin with a $, and can only contain alphanumeric characters and punctuation. Values can be numeric, boolean, Date objects, strings 255 characters or shorter, or nested objects whose values can be numeric, boolean, Date objects, arrays, strings, or null. Total size of event properties cannot exceed 50KB.
Whether or not the event was successfully logged (to be flushed later).
Logs that the news feed was displayed. This is done automatically when you use Appboy's display module and should only be called if you're bypassing that and manually building the class for displaying the cards in your own code.
Logs that the user clicked the given in-app message button. This is done automatically when the user clicks on
a button in a message generated by display.showInAppMessage,
and should only be called if you're bypassing that method and manually displaying the message in your own
code.
The button clicked
The message this button belongs to
Whether or not the event was successfully logged (to be flushed later).
Logs that the user clicked the given in-app message. This is done automatically when the user clicks on a
message generated by display.showInAppMessage, and should
only be called if you're bypassing that method and manually displaying the message in your own code.
Whether or not the event was successfully logged (to be flushed later).
Logs that the user clicked on a link in an html in-app message. This is done automatically when the user clicks
on a message generated by display.showInAppMessage, and should
only be called if you're bypassing that method and manually displaying the message in your own code.
The message that was clicked
A button id to associate this click with for analytics
The url that was clicked
Whether or not the event was successfully logged (to be flushed later).
Logs that the user saw the given in-app message. This is performed automatically when you use display.showInAppMessage,
and should only be called if you're bypassing that method and manually displaying the message in your own code.
Whether or not the event was successfully logged (to be flushed later).
Reports that the current user made an in-app purchase. Useful for tracking and segmenting users.
A string identifier for the product purchased, e.g. an SKU. Value is limited to 255 characters in length, cannot begin with a $, and can only contain alphanumeric characters and punctuation.
The price paid. Base units depend on the currency. As an example, USD should be reported as Dollars.Cents, whereas JPY should be reported as a whole number of Yen. All provided values will be rounded to two digits with toFixed(2)
Default USD. Currencies should be represented as an ISO 4217 currency code. Supported currency symbols include: AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTC, BTN, BWP, BYR, BZD, CAD, CDF, CHF, CLF, CLP, CNY, COP, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EEK, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GGP, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, IMP, INR, IQD, IRR, ISK, JEP, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MTL, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLL, SOS, SRD, STD, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VEF, VND, VUV, WST, XAF, XAG, XAU, XCD, XDR, XOF, XPD, XPF, XPT, YER, ZAR, ZMK, ZMW, and ZWL. Any other provided currency symbol will result in a logged warning and no other action taken by the SDK.
Default 1. The quantity of items purchased expressed as a whole number. Must be at least 1 and at most 100.
Hash of properties for this purchase. Keys are limited to 255 characters in length, cannot begin with a $, and can only contain alphanumeric characters and punctuation. Values can be numeric, boolean, Date objects, strings 255 characters or shorter, or nested objects whose values can be numeric, boolean, Date objects, arrays, strings, or null. Total size of purchase properties cannot exceed 50KB.
Whether or not the purchase was successfully attached to the session (to be flushed later).
Opens a new session, or resumes the previous session if this browser had activity within the last 30 minutes. When a new session is opened, syncs triggered In-App Messages and Content Cards. If the user has previously granted the site permission to send push, automatically sends the push registration to the Braze backend.
Register this browser environment to receive web push for this user. Supports browsers which implement the
W3C Push API (browsers in which
appboy.isPushSupported returns true). If push is supported and the user is not already subscribed,
this method will cause the browser to immediately request push permission from the user.
In order to properly use this feature, there are some integration steps required on your end:
service-worker.js file with the content below and place it in the root directory of your website:self.importScripts('https://js.appboycdn.com/web-sdk/{{VERSION}}/service-worker.js');For more details, see Our Product Documentation.
When the user subscribes to push successfully this callback will be invoked with the user's endpoint, public key, and user auth key (endpoint, publicKey, userAuth).
If push permission is denied, this callback will be invoked. If the denial
is temporary, it will be invoked with a parameter of true - otherwise it will be invoked with a parameter
of false.
Remove all event subscriptions.
Remove an event subscription that you previously subscribed to.
The identifier of the subscription you wish to remove, returned by the method you initially used to create it.
Requests an immediate refresh of content cards from Appboy servers. By default, content cards are refreshed when a new session opens (see 'openSession` for more details), and when the user refreshes content cards manually via the refresh button. If you want to refresh content cards from the server at another time you must call this function.
Callback that is invoked when the content cards refresh request has been successfully completed.
You should use subscribeToContentCardsUpdates to be notified of new cards. This callback is useful for determining when
a request has completed regardless of whether new cards were returned.
Callback that is invoked when an error occurs during the refresh.
Requests an immediate refresh of the news feed from Braze servers. By default, the news feed is refreshed on
display.showFeed (when stale - see
display.showFeed for details). If you want to refresh the feed from the
server at another time you must call this function. Results of this refresh are reported asynchronously to
subscriptions created via 'subscribeToFeedUpdates` .
By default, data logged to Braze through the SDK is queued locally (in HTML 5 localStorage when available, and in memory otherwise) and sent to Braze's servers asynchronously on a regular interval (10 seconds when localStorage is available and not routinely cleared due to browser privacy features, otherwise 3 seconds). This is done to optimize network usage and provide resiliency against network or server outages. This method bypasses the interval and immediately flushes queued data.
Invoked when the flush completes with a boolean parameter that returns whether or not the flush was successful. If the flush is unsuccessful, pending data will be flushed during the next successful flush.
Removes the cookie set by stopWebTracking, causing subsequent calls to the Braze Web SDK to function. You must
call initialize after calling this method before calling subsequent methods.
By default, Braze logs to the browser console. Call this method to set a custom log action and enable debug-level log statements.
A function to invoke with log messages. Should accept a single string parameter for message.
Sets the signature to be used to authenticate the current user. You can also set the signature when calling changeUser.
This signature will only have an effect if the enableSdkAuthentication initialization option is set to true.
The signature to add to network requests to authenticate the current user.
Whether or not the signature is valid.
Sets a cookie that causes all subsequent calls to the Braze Web SDK to be ignored and all subsequent analytics to cease being sent to the Braze backend. If you have multiple subdomains, this method MUST be called from the same subdomain that push was registered from to work properly. This is useful for customer opt-outs. If the customer clears website data, tracking will resume.
Subscribe to content cards updates. The subscriber callback will be called whenever content cards are updated.
The callback function to handle new cards. This function will be called with a ContentCards
object which includes all currently available Card objects. If you want to be notified when a refresh has completed
regardless of whether new cards are available, you should use the successCallback of requestContentCardsRefresh.
The identifier of the subscription created. This can be passed to removeSubscription to cancel the subscription.
Subscribe to news feed updates. The subscriber callback will be called whenever the news feed is updated.
The callback function to handle new cards. This function will be
called with a Feedobject which includes all Card objects currently in the feed.
The identifier of the subscription created. This can be passed to
removeSubscription to cancel the subscription.
Subscribe to receive in-app messages. The subscriber callback will be called whenever a new in-app message is triggered. If you are using the build of Braze's library with UI, the most basic usage of this would be
appboy.subscribeToInAppMessage(function(inAppMessage) {
appboy.display.showInAppMessage(inAppMessage);
});The callback function to handle the in-app message. This function will be
called with an InAppMessage or a ControlMessage object. If you are using the build
of Braze's library with UI, you may wish to call display.showInAppMessage
with the provided message.
The identifier of the subscription created. This can be passed to 'removeSubscription` to cancel the subscription.
DEPRECATED - Subscribe to receive in-app messages. The subscriber callback will be called whenever new in-app messages are triggered. If you are using the build of Braze's library with UI, the most basic usage of this would be
appboy.subscribeToNewInAppMessages(function(inAppMessages) {
appboy.display.showInAppMessage(inAppMessages[0]);
return inAppMessages.slice(1);
});The identifier of the subscription created. This can be passed to 'removeSubscription` to cancel the subscription.
Subscribe to be notified of network request failures that occured due to an SDK Authentication error. This
method can be used to determine when to call setSdkAuthenticationSignature to provide the SDK with a new signature.
If you do not have SDK Authentication enabled on the Braze dashboard, this subscription will never be invoked.
The subscriber function that is invoked whenever an SDK Authentication error occurs. It is
invoked with an object containing the errorCode, reason for the error, the userId of the request (if the
user is not anonymous), and the authentication signature that caused the error.
By default, Braze silences its logging to prevent spamming production js consoles. Call this method to toggle logging.
Causes the Braze Web SDK to begin continuously collecting the user's location while your website is visible in the foreground of their browser, for the duration of this page load. This will cause the browser to request permission from the user if they have not already granted or denied it.
Unregisters push notifications on this browser. Note that for Safari, Apple does not offer any unsubscribe mechanism, so on Safari this method leaves the user with push permission granted and simply sets their subscription status to unsubscribed.
When the unsubscribe is successfully recorded and processed by Braze, this callback will be invoked.
If the unsubscribe fails for unknown reasons, this callback will be invoked.
Removes all locally stored SDK data, causing the user to be seen in subsequent calls as a new anonymous user on a new device.
Supported initialization options