# Braze Web-Mode (Actions) Destination

## Destination Info

* Accepts [Page](/docs/segment/connections/spec/page), [Group](/docs/segment/connections/spec/group), [Identify](/docs/segment/connections/spec/identify), [Track](/docs/segment/connections/spec/track) calls.
* Refer to it as **Braze Web Mode (Actions)**, **Braze Web Device Mode (Actions)** in the [Integrations object.](/docs/segment/guides/filtering-data/#filtering-with-the-integrations-object)
* This destination is not compatible with [Destination Insert Functions.](/docs/segment/connections/functions/insert-functions/)

> \[!NOTE]
>
> This page is about the Braze Web-Mode (Actions) Destination. See below for information about other versions of the Braze destination:
>
> * [Braze Cloud-Mode (Actions)](/docs/segment/connections/destinations/catalog/actions-braze-cloud)
> * [Braze (Classic)](/docs/segment/connections/destinations/catalog/braze)

[Braze](https://www.braze.com/), formerly Appboy, is an engagement platform that empowers growth by helping marketing teams to build customer loyalty through mobile, omni-channel customer experiences.

## Benefits of Braze Web-Mode (Actions) vs Braze (Classic)

Braze web-mode (Actions) provides the following benefits over Braze (Classic):

* **E-commerce mappings**. Users who can't follow the e-commerce spec due to incompatible event names (for example, Trip Booked vs Order Completed) can log purchases in Braze web-mode (Actions).

## Getting Started

1. From the Segment web app, navigate to **Connections > Catalog**.
2. Search for "Braze" in the Catalog in the Destinations Catalog and select **Braze**.
3. Choose which of your sources to connect the destination to and follow the steps to create your destination.

> \[!WARNING]
>
> Some events require specific property names to map correctly into Braze.
> For example, purchase events must use a `products` array with `product_id` and `price`.
> See [Braze-web settings mappings](#braze-web-settings-mapping) for "Device-web" for the full list of requirements before setting up mappings.

4. In the **Settings** tab, configure the connection settings. **API Key**, **SDK Endpoint**, and **REST Endpoint** are required settings.

After setting up your Braze web-mode (Action) destination in the Segment app, Segment's Analytics.js library starts asynchronously loading the Braze SDK on your page and sending data. Data appears in the Segment CDN in about 45 minutes.

> \[!NOTE]
>
> If you're using a device-mode connection, Braze's SDK assigns a `device_id` and a backend identifier, `braze_id`, to every user. This allows Braze to capture anonymous activity from the device by matching on those identifiers instead of `userId`. This applies to *device-mode connections*.

## Destination Settings

| Field                                               | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Required | Type     |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------- |
| Allow Crawler Activity                              | Allow Braze to log activity from crawlers. \[See more details]\(https://js.appboycdn.com/web-sdk/latest/doc/modules/appboy.html#initializationoptions)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | No       | boolean  |
| Allow User Supplied Javascript                      | To indicate that you trust the Braze dashboard users to write non-malicious Javascript click actions, set this property to true. \[See more details]\(https://js.appboycdn.com/web-sdk/latest/doc/modules/appboy.html#initializationoptions)                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | No       | boolean  |
| API Key                                             | Found in the Braze Dashboard under Manage Settings → Apps → Web                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Yes      | password |
| App Version                                         | Version to which user events sent to Braze will be associated with. \[See more details]\(https://js.appboycdn.com/web-sdk/latest/doc/modules/appboy.html#initializationoptions)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | No       | string   |
| Automatically Send In-App Messages                  | When this is enabled, all In-App Messages that a user is eligible for are automatically delivered to the user. If you'd like to register your own display subscribers or send soft push notifications to your users, make sure to disable this option.                                                                                                                                                                                                                                                                                                                                                                                                                                                        | No       | boolean  |
| Content Security nonce                              | Allows Braze to add the nonce to any \<script> and \<style> elements created by the SDK. \[See more details]\(https://js.appboycdn.com/web-sdk/latest/doc/modules/appboy.html#initializationoptions)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | No       | string   |
| Only Track Known Users                              | If enabled, this setting delays initialization of the Braze SDK until the user has been identified. When enabled, events for anonymous users will no longer be sent to Braze.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | No       | boolean  |
| Device Property Allow List                          | By default, the Braze SDK automatically detects and collects all device properties in DeviceProperties. To override this behavior, provide an array of DeviceProperties. \[See more details]\(https://js.appboycdn.com/web-sdk/latest/doc/modules/appboy.html#initializationoptions)                                                                                                                                                                                                                                                                                                                                                                                                                          | No       | array    |
| Disable Push Token Maintenance                      | By default, users who have already granted web push permission 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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | No       | boolean  |
| Do Not Load Font Awesome                            | Braze automatically loads FontAwesome 4.7.0 from the FontAwesome CDN. To disable this behavior set this option to true.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | No       | boolean  |
| Enable Logging                                      | Set to true to enable logging by default                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | No       | boolean  |
| Enable SDK Authentication                           | Set to true to enable the SDK Authentication feature.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | No       | boolean  |
| SDK Endpoint                                        | Your Braze SDK endpoint. \[See more details]\(https://www.braze.com/docs/user\_guide/administrative/access\_braze/sdk\_endpoints/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Yes      | select   |
| In-App Message Z Index                              | 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                          | No       | number   |
| Localization                                        | 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                 | No       | string   |
| Manage Service Worker Externally                    | 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. \[See more details]\(https://js.appboycdn.com/web-sdk/latest/doc/modules/appboy.html#initializationoptions)                                                                                                                                                                                                                                                                                                                                                                                                                   | No       | boolean  |
| Minimum Interval Between Trigger Actions in Seconds | Provide a value to override the default interval between trigger actions with a value of your own. \[See more details]\(https://js.appboycdn.com/web-sdk/latest/doc/modules/appboy.html#initializationoptions)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | No       | number   |
| No Cookies                                          | By default, the Braze SDK will store small amounts of data (user ids, session ids), in cookies. Pass true for this option to disable cookie storage and rely entirely on HTML 5 localStorage to identify users and sessions. \[See more details]\(https://js.appboycdn.com/web-sdk/latest/doc/modules/appboy.html#initializationoptions)                                                                                                                                                                                                                                                                                                                                                                      | No       | boolean  |
| Open Cards In New Tab                               | 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | No       | boolean  |
| Open In-App Messages In New Tab                     | 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                             | No       | boolean  |
| Require Explicit In-App Message Dismissal           | 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.                                                                                                                                                                                                                                                                                                                                                                                                                                            | No       | boolean  |
| Safari Website Push ID                              | 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").                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | No       | string   |
| SDK Version                                         | The version of the Braze SDK to use                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Yes      | select   |
| Service Worker Location                             | 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/. | No       | string   |
| Session Timeout in Seconds                          | 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | No       | number   |

## Available Presets

Braze Web Device Mode (Actions) has the following presets

| Preset Name           | Trigger                                             | Default Action      |
| --------------------- | --------------------------------------------------- | ------------------- |
| Order Completed calls | Event type = "track" and event = "Order Completed"  | Track Purchase      |
| Track Calls           | Event type = "track" and event != "Order Completed" | Track Event         |
| Identify Calls        | Event type = "identify", Event  type = "group"      | Update User Profile |

## Available Actions

Build your own Mappings. Combine supported [triggers](/docs/segment/connections/destinations/actions/#components-of-a-destination-action) with the following Braze Web Device Mode-supported actions:

> \[!NOTE]
>
> Individual destination instances have support a maximum of 50 mappings.

* [Debounce Middleware](#debounce-middleware)
* [Track Event](#track-event-39)
* [Update User Profile](#update-user-profile)
* [Track Purchase](#track-purchase-4)

### Debounce Middleware

When enabled, it ensures that only events where at least one changed trait value are sent to Braze, and events with duplicate traits are not sent. Debounce functionality requires a frontend client to work. Therefore, it cannot be used with server-side libraries or with Engage.

Debounce Middleware is a **Web** action. The default Trigger is `type = "identify" or type = "group"`

This action does not have any fields.

### Track Event

Reports that the current user performed a custom named event.

Track Event is a **Web** action. The default Trigger is `type = "track" and event != "Order Completed"`

| Field            | Description                            | Required | Type   |
| ---------------- | -------------------------------------- | -------- | ------ |
| Event Name       | The identifier for the event to track. | Yes      | STRING |
| Event Properties | Hash of properties for this event.     | No       | OBJECT |

### Update User Profile

Updates a users profile attributes in Braze

Update User Profile is a **Web** action. The default Trigger is `type = "identify" or type = "group"`

| Field               | Description                                                                                                                                                                                                    | Required | Type     |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------- |
| External User ID    | The unique user identifier                                                                                                                                                                                     | No       | STRING   |
| Country             | The country code of the user                                                                                                                                                                                   | No       | STRING   |
| Current Location    | The user's current longitude/latitude.                                                                                                                                                                         | No       | OBJECT   |
| Custom Attributes   | Sets a custom user attribute. This can be any key/value pair and is used to collect extra information about the user.                                                                                          | No       | OBJECT   |
| Date of Birth       | The user's date of birth                                                                                                                                                                                       | No       | DATETIME |
| Email               | The user's email                                                                                                                                                                                               | No       | STRING   |
| Email Subscribe     | The user's email subscription preference: “opted\_in” (explicitly registered to receive email messages), “unsubscribed” (explicitly opted out of email messages), and “subscribed” (neither opted in nor out). | No       | STRING   |
| First Name          | The user's first name                                                                                                                                                                                          | No       | STRING   |
| Last Name           | The user's last name                                                                                                                                                                                           | No       | STRING   |
| Gender              | The user's gender: “M”, “F”, “O” (other), “N” (not applicable), “P” (prefer not to say) or nil (unknown).                                                                                                      | No       | STRING   |
| Home City           | The user's home city.                                                                                                                                                                                          | No       | STRING   |
| Image URL           | URL of image to be associated with user profile.                                                                                                                                                               | No       | STRING   |
| Language            | The user's preferred language.                                                                                                                                                                                 | No       | STRING   |
| Phone Number        | The user's phone number                                                                                                                                                                                        | No       | STRING   |
| Push Subscribe      | The user's push subscription preference: “opted\_in” (explicitly registered to receive push messages), “unsubscribed” (explicitly opted out of push messages), and “subscribed” (neither opted in nor out).    | No       | STRING   |
| Subscription Groups | A list of subscription group IDs and states to set. Subscription group states can be either "subscribed" or "unsubscribed". Subscription Group IDs are found in the Braze dashboard.                           | No       | OBJECT   |

### Track Purchase

Reports that the current user made an in-app purchase.

Track Purchase is a **Web** action. The default Trigger is `type = "track" and event = "Order Completed"`

| Field               | Description                                                                                                                                                                                                                                                                                                                                                                                                     | Required | Type   |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------ |
| Purchase Properties | 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. | No       | OBJECT |
| Products            | List of products purchased by the user                                                                                                                                                                                                                                                                                                                                                                          | No       | OBJECT |

## Other features

Braze web-mode (Actions) can use the following features of Braze.

### In-app messaging

Once configured, you can trigger in-app message display as a result of several different event types. By default, all In-App Messages that a user is eligible for are automatically delivered to the user upon a session start event. A new session automatically starts when a user loads your site. If you'd like to force a new session for a user, make an [Identify](/docs/segment/connections/spec/identify/) call with the corresponding [userId](/docs/segment/connections/spec/identify/#user-id) for that user.

If you don't want your site to display new In-App Messages as they're received, disable automatic display and register your own display subscribers. To do this:

Create your subscriber by calling:

```js
analytics.ready(function() {
  window.appboy.subscribeToNewInAppMessages(function(inAppMessages) {
      // Display the first in-app message. You could defer display here by pushing this message to code      within in your own application.
      // If you don't want to use Appboy's built-in display capabilities, you could alternatively pass      the in-app message to your own display code here.
      window.appboy.display.showInAppMessage(inAppMessages[0]);

    // Return an array with any remaining, unhandled messages to appboy's internal queue.
    // These will be part of the inAppMessages param the next time this subscriber is invoked.
      return inAppMessages.slice(1);
    });
});
```

The `inAppMessages` parameter will be an array of [`appboy.ab.InAppMessage`](https://js.appboycdn.com/web-sdk/latest/doc/ab.InAppMessage.html) subclass or [`appboy.ab.ControlMessage`](https://js.appboycdn.com/web-sdk/latest/doc/ab.ControlMessage.html) objects, each of which has various lifecycle event subscription methods.

### Push notifications

1. To support push notifications on Chrome, you must enable FCM/GCM and configure your site. See steps [one and two in the Braze docs for detailed instructions on both](https://www.braze.com/docs/developer_guide/platform_integration_guides/web/initial_sdk_setup#step-1-to-support-chrome-enable-fcmgcm).
2. **Browser Registration**: For a browser to receive push notifications, you must register it for push by calling:

   ```js
   analytics.ready(function() {
     window.appboy.registerAppboyPushMessages();
   });
   ```

   **Note**: Place this snippet outside of your [Segment Snippet](/docs/segment/connections/sources/catalog/libraries/website/javascript/quickstart/#step-2-copy-the-segment-snippet) within your `script` tag.

   **Note**: This requests push permission from the user.

To show your own push-related UI to the user before requesting push permission (known as a soft push prompt), you can test to see if the user's browser supports push by calling:

```js
analytics.ready(function() {
  if (window.appboy.isPushSupported()) {
    // Add your push logic
  }
 });
```

Braze recommends checking to see if this returns `true` since not all browsers can receive push notifications. See [Soft Push Prompts](#soft-push-prompts) for instructions on setting up a soft push prompt using Braze In-App Messages.

To unsubscribe a user, call:

```js
analytics.ready(function() {
  window.appboy.unregisterAppboyPushMessages();
});
```

1. Set your GCM/FCM server API key and SenderID on the Braze dashboard. You can find more details for this in Braze's [Initial SDK setup for web](https://www.braze.com/docs/developer_guide/platform_integration_guides/web/initial_sdk_setup#step-4-set-your-gcmfcm-server-api-key-and-senderid-on-the-Braze-dashboard) documentation.
2. To support push notifications on Safari, add your Website Push ID into your Segment Settings UI and Segment sends it when the Braze Web SDK initializes. To get your Website Push ID, follow the first two bullet points in [these instructions](https://www.braze.com/docs/developer_guide/platform_integration_guides/web/initial_sdk_setup#step-5-configure-safari-push).

### Soft push prompts

1. Follow [step one](https://www.braze.com/docs/developer_guide/platform_integration_guides/web/push_notifications/soft_push_prompt/#step-1-create-a-push-primer-campaign) detailed in the Braze docs, to create a "Prime for Push" in-app messaging Campaign on the Braze dashboard.
2. Add the following snippet to your site:

```js
analytics.ready(function() {
  window.appboy.subscribeToNewInAppMessages(function(inAppMessages) {
    var message = inAppMessages[0];
    if (message != null) {
      var shouldDisplay = true;

      if (message instanceof appboy.ab.inAppMessage) {
        // Read the key/value pair for msg-id
        var msgId = message.extras["msg-id"];

        // If this is our push primer message
        if (msgId == "push-primer") {
          // We don't want to display the soft push prompt to users on browsers that don't support push, or if the user
          // has already granted/blocked permission
          if (!appboy.isPushSupported() || appboy.isPushPermissionGranted() || appboy.isPushBlocked())     {
            shouldDisplay = false;
          }
          // Prompt the user when the first button is clicked
          message.buttons[0].subscribeToClickedEvent(function() {
            appboy.registerAppboyPushMessages();
          });
        }
      }

      // Display the message
      if (shouldDisplay) {
        appboy.display.showInAppMessage(message);
      }
     }

    // Remove this message from the array of IAMs and return whatever's left
    return inAppMessages.slice(1);
   });
 });
```

For more details on this snippet, see Braze's [Soft push prompt](https://www.braze.com/docs/developer_guide/platform_integration_guides/web/push_notifications/soft_push_prompt/#step-3-update-integration) documentation.

> \[!NOTE]
>
> Place this snippet outside of your [Segment Snippet](/docs/segment/connections/sources/catalog/libraries/website/javascript/quickstart/#step-2-copy-the-segment-snippet) within your `script` tag.

1. When you'd like to display the Soft Push to a user, call:

```js
 analytics.ready(function() {
  window.appboy.logCustomEvent("prime-for-push")
 });
```

### Enable SDK authentication

When "Enable SDK Authentication" is enabled, Segment will set Braze's `enableSdkAuthentication` to `true`. When this feature is enabled, the Braze SDK will append the current user's last known JWT to network requests made to Braze Servers.

## Important differences from Braze (Classic) destination

* Braze web-mode (Actions) supports the Braze [Web](https://github.com/segment-integrations/analytics.js-integration-appboy) integration. [Braze Cloud-Mode (Actions)](/docs/segment/connections/destinations/catalog/actions-braze-cloud) supports server and mobile sources, but to use mobile sources in device-mode, use the Braze Classic destination.

## Migration from Braze (Classic)

Keep the following in mind if you plan to move to Braze (Actions) from the classic Braze destination.

### Braze-web settings mappings

#### CONNECTION SETTINGS

* **App Identifier** (CLOUD, DEVICE-WEB):
  * Global Setting
  * The setting is called App ID
* **REST API Key** (CLOUD):
  * This setting is renamed \*\*API Key\*\* in the Braze Web Mode (Actions) Connection Settings.
* **Appboy Datacenter** (CLOUD):
  * This setting is covered by the SDK Endpoint in Braze Web Mode (Actions) Connection Settings.
* **Log Purchase when Revenue is present** (DEVICE-WEB):
  * Modify the Trigger for the Track Purchase action to recreate this behavior in Braze (Actions). By default, events named "Order Completed" trigger this action, but you can update the Trigger to check for a property named \`revenue\`. The event must have a \`products\` array with \`product\_id\` and \`price\`.
* **Safari Website Push ID** (DEVICE-WEB):
  * This setting is available in the Braze Web Mode (Actions) Connection Settings.
* **Braze Web SDK Version** (DEVICE-WEB):
  * Available in the \*\*SDK Version\*\* Connection Setting. Defaults to version 3.3.
* **Connection Mode** (CLOUD, DEVICE-WEB):
  * Choose the version of the Braze (Actions) destination that matches your connection mode.

#### IN-APP MESSAGING

* **Do Not Load Font Awesome** (DEVICE-WEB):
  * Available in the Braze Web Mode (Actions) Connection Settings.
* **Open In-App Messages in New Tab** (DEVICE-WEB):
  * Available in the Braze Web Mode (Actions) Connection Settings.

#### PAGE

* **Track All Pages** (DEVICE-WEB):
  * Create a \*\*Track Event\*\* subscription and update the Event Trigger to specify \`Event Type is Page\` and \`Event Property 'name' exists\`. Update the Event Name field for the Track Event action to "Viewed Page \{name}". Use the Event Variables selector to select the \`name\` variable.
* **Track Only Named Pages** (DEVICE-WEB):
  * Create a \*\*Track Event\*\* subscription and update the Event Trigger to specify \`Event Type is Page\` and. Update the Event Name field for the Track Event action to "Viewed Page \{name}". Use the Event Variables selector to select the \`name\` variable.

#### OTHER SETTINGS

* **Allow Crawler Activity** (DEVICE-WEB):
  * Available in the Braze Web Mode (Actions) Connection Settings.
* **Enable Logging** (DEVICE-WEB):
  * Available in the Braze Web Mode (Actions) Connection Settings.
* **Minimum Interval Between Trigger Actions in Seconds** (DEVICE-WEB):
  * Available in the Braze Web Mode (Actions) Connection Settings.
* **Open News Feed Cards in New Tab** (DEVICE-WEB):
  * Available in the Braze Web Mode (Actions) Connection Settings.
* **Service Worker Location** (DEVICE-WEB):
  * Available in the Braze Web Mode (Actions) Connection Settings.
* **Session Timeout in Seconds** (DEVICE-WEB):
  * Available in the Braze Web Mode (Actions) Connection Settings.

## FAQs

#### How does the Debounce Middleware Action work?

The following [Debounce Middleware](/docs/segment/connections/destinations/catalog/actions-braze-web/#debounce-middleware) logic is executed at the source-level:

When an Identify call is fired on a website, Segment first caches and compares the user traits object.

* If the user traits differ from what was previously cached, the data flows through destination filters, insert functions, and then through destination mappings.
* If user traits are the same as what's cached, Segment assumes that that data was already sent to Braze and a does not make a new request to Braze.