Event

Braze is a comprehensive customer engagement platform that powers relevant experiences between consumers and brands they love. Braze helps brands foster human connection through interactive conversations across channels.

Braze offers a broad range of functionality via their solution and it is critically important that you work directly with your Braze representative to ensure that you are correctly planning and implementing their features. mParticle does not recommend enabling forwarding to Braze until you have completed the Braze planning process with your Braze team.

• Braze Documentation

mParticle Braze Implementation Scenarios

The mParticle SDK allows you to include the Braze kit which allows Braze interface components (images, layout files, etc.) and as a result supports many Braze features, including:

• App Analytics
• User Segmentation
• Push Notifications
• Email
• News Feed
• In-App Messaging
• Feedback
• Geolocation

Features are supported by the mParticle SDK only after you install the mParticle Braze Kit (formerly Appboy), which then forwards data from your app to Braze.

Features are supported in two ways:

• The kit itself provides functionality directly without you having to call the third-party SDK. For example, most partners have a method called or equivalent to logEvent. When someone calls mParticle.logEvent, our kits map to the partner SDK logEvent method, in this case, Braze.logEvent, and automatically sends it to Braze. You don’t have to call Braze.logEvent because mParticle does it for you after you call mParticle.logEvent.
• For some features, for example some Braze banners or modals, you must call Braze.bannerMethod() or Braze.modalMethod(). Our kit loads Braze so that you can call any Braze method you need, even if our kit does not call it for you.

The mParticle S2S API allows you to send data server side (API reference). The S2S API supports iOS, Android and Web data. In this scenario, mParticle forwards data via Braze’s REST API which supports a limited set of features.

For server-side data to be forwarded to Braze, it must include your selected External Identity Type. To relax this requirement, see the Disable External ID Constraint connection setting.

The following event types can be forwarded to Braze via S2S:

• Commerce Event
• Custom Event
• Opt Out
• Push Message
• Push Message Registration
• Screen View
• Session Start / End

Kit Integration

The Braze solution offers features that involve Braze-proprietary user interaction components including Newsfeed, In-App Messaging, and Feedback.

To use Braze with one of the mParticle mobile SDKs, please review the kit documentation for the Android SDK or the iOS SDK.

You must directly call the Braze kit to use the Newsfeed, In-App Messaging, and Feedback features. Examples of directly calling a kit are provided for both Android and iOS.

Braze v9 iOS SDK Upgrade Notes

To comply with Apple’s iOS 17 privacy manifest it is required to update to Braze SDK version 9.0.0 or later which is included by the mParticle Braze Kit version 8.60 or later. Note that it is also required to update to at least version 8.24.0 of the mParticle SDK if you are not creating your own Braze instance and passing it to the mParticle Braze Kit in order for this functionality to work.

There are also additional steps required to comply which are outlined in the Braze documentation here.

If you are creating your own Braze instance and passing it to the mParticle Kit as described in the iOS App Launch Tracking section below, you can simply follow instructions in the above Braze documentation directly.

If not, you will still need to follow the above Braze documentation, with the following exceptions:

1. Set the trackingPropertyAllowList property on the mParticle Braze Kit before starting the mParticle SDK instead of setting it on the Braze instance directly.

// In this example, we're setting phone number and email as tracking data.
// Replace the values in the allow list with the data you are tracking
MPKitAppboy.setBrazeTrackingPropertyAllowList([.email, .dateOfBirth])

// In this example, we're setting phone number and email as tracking data.
// Replace the values in the allow list with the data you are tracking
NSSet *allowList = [NSSet setWithArray:@[BRZTrackingProperty.phoneNumber, BRZTrackingProperty.email]];
[MPKitAppboy setBrazeTrackingPropertyAllowList:allowList];

2. In your ATTrackingManager request callback, call the corresponding method on the mParticle SDK instead of setting it on the Braze instance directly.

ATTrackingManager.requestTrackingAuthorization { status in
    let mpStatus = MPATTAuthorizationStatus(rawValue: status.rawValue) ?? .notDetermined
    let timestampMillis: NSNumber = (Date().timeIntervalSince1970 * 1000) as NSNumber
    MParticle.sharedInstance().setATTStatus(mpStatus, withATTStatusTimestampMillis: timestampMillis)
}

[ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {
    MPATTAuthorizationStatus mpStatus = (MPATTAuthorizationStatus)status;
    NSNumber *timestampMillis = @(NSDate.now.timeIntervalSince1970 * 1000);
    [MParticle.sharedInstance setATTStatus:mpStatus withATTStatusTimestampMillis:timestampMillis];
}];

Push Notifications

Push notifications work differently for web and for mobile.

Web

mParticle integrates with Braze to allow web push notifications to further engage your visitors. We integrated Braze’s Soft Push Prompts, which allows you to ask your user if they’d like to stay in touch before the browser alerts them to allow notifications. This is done since the browser throttles how often you can prompt the user for push notifications, and if the user denies permission, you can never ask them again. See below for directions on how to implement push notifications, which customizes Braze’s implementation instructions to work with mParticle.

1. Configure your site

   • Create a service-worker.js file to your root directory. Inside your service-worker.js file, include

   self.importScripts('https://static.mparticle.com/sdk/js/braze/service-worker-3.5.0.js');

   mParticle hosts Braze’s service worker in order to prevent unpredictable versioning issues. Do not use Braze’s service-worker.js CDN.

2. Configure Safari Push

   • Generate a Safari Push Certificate following these “Registering with Apple” Instructions
   • In the Braze dashboard, on the app settings page (where your API keys are located), select your Web app. Click “Configure Safari Push” and follow the instructions, uploading the push certificate you just generated.
   • In your mParticle dashboard, open your Braze connection settings. Under Safari Website Push ID, type in your Website Push ID you used when generating your Safari Push Certificate (beginning with web) and click Save.

3. Create a “Prime for Push” in-app messaging Campaign on the Braze dashboard. Note that this is an In-App Messaging Campaign, and not a Push Notification messaging campaign.

   • Make it a “Modal” In-App Message. Give it whatever text and styling you wish to present to the user (“Can we stay in touch?”).
   • Give the in-app message a Button 1 Text value of “OK” (or whatever affirmative text you wish), and set the On-Click Behavior to “Close Message.”
   • Under the gear composer section, add a key-value pair. Give it a key of msg-id and a value of push-primer.
   • You can create a prime-for-push custom event (or name it whatever you’d like) from the Braze dashboard. While still in the Braze dashboard, create a trigger action of whatever your custom event is (ie, prime-for-push). In the mParticle Braze connection settings, fill in the "Soft Push" Custom Event Name with your custom event name (ie. prime-for-push). When this field is filled, users will be sent the Soft Push Prompt on session load.

   • Optionally, you can change the name and location of service-worker.js. The following example will clarify the steps:

     • Let’s say that you want to rename your service-worker.js file to braze-push-worker.js and store it in inside a directory in your root folder called thirdParty/.
     • In your mParticle dashboard, open your Braze connection settings. Under Push Notification Service Worker File Location, type in /thirdParty/braze-push-worker.js and click Save.
     • Warning - 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 /thirdParty/ directory, asking for push notifications MAY ONLY BE CALLED from web pages that start with http://your-site-name.com/thirdParty/.

Web Troubleshooting Tips

• Firefox - starting with version 72, Firefox requires user interaction before showing a full push permission dialogue box. See here for more details.
• Ensure that your OS-wide notifications for the browser you are testing are not disabled.
• If you have previously allowed or rejected push requests while testing, you will need to clear local storage/cookies as well as the browser’s notification preference for your development URL for optimal testing.

Mobile

As long as the Braze Kit is included in your app, mParticle will pass any Push Notifications from Braze to the kit for display. However, you will need to provide credentials in the Braze dashboard.

See the main iOS and Android Push Notification documentation for more detail.

iOS App Launch Tracking

On iOS, when a user launches your app by tapping on a push notification, you may see these launches recorded in the mParticle dashboard but not in Braze. This happens due to a race condition between the Braze SDK initializing and the app handling the push notification.

To work around this, you’ll need to create your own instance of Braze in your applicationDidFinishLaunching method of your app delegate and pass it to the Braze kit before initializing the mParticle SDK. You’ll also need to tell the kit not to process push notifications and instead handle them yourself. This ensures that Braze is initialized and ready to receive the push notifications immediately upon app launch.

Note that by implementing your own instance of Braze, you will lose the ability to use the following Braze configuration options in the mParticle dashboard, as you’ll be passing those options to Braze yourself on app launch. Only implement this if you need push notification app launches reported to Braze:

• Braze API Key
• Braze Endpoint
• Braze SDK Request Policy
• Braze SDK Flush Interval
• Braze SDK Session Timeout
• Braze SDK Minimum Time Interval Between Triggers
• Braze SDK Disable Automatic Location Tracking

All other Braze configuration options in the mParticle dashboard will continue to work as usual, and any of the above can be set in your app when you create the Braze instance by setting the relevant options on the Braze configuration object. See the example code for the didFinishLaunchingWithOptions method below.

The following is mostly following the instructions from Braze’s “Manual push integration” documentation, with the addition of some mParticle specific code in the didFinishLaunchingWithOptions method.

Please note that because we are following Braze’s “Manual push integration” instructions, you should not set the configuration option, configuration.push.automation = true, as described in Braze’s Automatic push integration documentation as it will cause conflicts.

1. Make sure to import the Braze SDK and mParticle Braze kit in your app delegate file.

import BrazeKit
import mParticle_Appboy

@import BrazeKit;
@import mParticle_Appboy;

2. Create and configure a Braze instance immediately upon app launch and pass it to the Braze kit.

var braze: Braze? = nil

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // Register for remote notifications
    application.registerForRemoteNotifications()
    let center = UNUserNotificationCenter.current()
    center.setNotificationCategories(Braze.Notifications.categories)
    center.delegate = self
    
    // Request user authorization to send push notifications
    var options: UNAuthorizationOptions = [.alert, .sound, .badge]
    if #available(iOS 12.0, *) {
        options = UNAuthorizationOptions(rawValue: options.rawValue | UNAuthorizationOptions.provisional.rawValue)
    }
    center.requestAuthorization(options: options) { granted, error in
        print("Notification authorization, granted: \(granted), error: \(String(describing: error))")
    }
    
    // Create the Braze configuration object
    // API key and endpoint were previously configured in the mParticle dashboard
    let configuration = Braze.Configuration(apiKey: "[YOUR_BRAZE_API_KEY]", endpoint: "[YOUR_BRAZE_ENDPOINT]")
    configuration.api.addSDKMetadata([.mparticle])
    configuration.api.sdkFlavor = .mparticle
    
    // Default mParticle dashboard options
    configuration.location.automaticLocationCollection = true
    
    // Optionally set any additional configuration options you would like here
    
    // Create a Braze instance with your chosen configuration and store the reference
    let braze = Braze(configuration: configuration)
    self.braze = braze
    
    // Pass the instance to the mParticle Braze kit so it can be used for other Braze functionality
    MPKitAppboy.setBrazeInstance(braze)
    
    // Instruct the mParticle Braze kit to not handle push notifications, as they'll be handled in the app delegate
    MPKitAppboy.setShouldDisableNotificationHandling(true)

    // Place your existing application initialization code here
}

// In the app delegate class header
//
@interface AppDelegate () <UNUserNotificationCenterDelegate>
@property (nonatomic, strong) Braze *braze;
@end

// In the app delegate class implementation
//
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Register for remote notifications
    [application registerForRemoteNotifications];
    UNUserNotificationCenter *center = UNUserNotificationCenter.currentNotificationCenter;
    [center setNotificationCategories:BRZNotifications.categories];
    center.delegate = self;
    
    // Request user authorization to send push notifications
    UNAuthorizationOptions options = UNAuthorizationOptionAlert | UNAuthorizationOptionSound | UNAuthorizationOptionBadge;
    if (@available(iOS 12.0, *)) {
        options = options | UNAuthorizationOptionProvisional;
    }
    [center requestAuthorizationWithOptions:options completionHandler:^(BOOL granted, NSError *_Nullable error) {
        NSLog(@"Notification authorization, granted: %d, error: %@)", granted, error);
    }];
    
    // Create the Braze configuration object
    // API key and endpoint were previously configured in the mParticle dashboard
    BRZConfiguration *configuration = [[BRZConfiguration alloc] initWithApiKey:@"[YOUR_BRAZE_API_KEY]" endpoint:@"[YOUR_BRAZE_ENDPOINT]"];
    [configuration.api addSDKMetadata:@[BRZSDKMetadata.mparticle]];
    configuration.api.sdkFlavor = BRZSDKFlavorMparticle;
    
    // Default mParticle dashboard options
    configuration.location.automaticLocationCollection = YES;
    
    // Optionally set any additional configuration options you would like here
    
    // Create a Braze instance with your chosen configuration and store the reference
    self.braze = [[Braze alloc] initWithConfiguration:configuration];

    // Pass the instance to the mParticle Braze kit so it can be used for other Braze functionality
    [MPKitAppboy setBrazeInstance:self.braze];
    
    // Instruct the mParticle Braze kit to not handle push notifications, as they'll be handled in the app delegate
    [MPKitAppboy setShouldDisableNotificationHandling:YES];
    
    // Place your existing application initialization code here
}

3. Add the required push notification delegate methods

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    self.braze?.notifications.register(deviceToken: deviceToken)
}
    
func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    if let braze = self.braze, braze.notifications.handleBackgroundNotification(userInfo: userInfo, fetchCompletionHandler: completionHandler) {
        return
    }
    completionHandler(.noData)
}

//...//

extension AppDelegate: UNUserNotificationCenterDelegate {
    func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
        if let braze = self.braze, braze.notifications.handleUserNotification(response: response, withCompletionHandler: completionHandler) {
            return
        }
        completionHandler()
    }

    func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
        if #available(iOS 14, *) {
            completionHandler([.list, .banner])
        } else {
            completionHandler(.alert)
        }
    }
}

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    [self.braze.notifications registerDeviceToken:deviceToken];
}

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
    BOOL processedByBraze = self.braze != nil && [self.braze.notifications handleBackgroundNotificationWithUserInfo:userInfo fetchCompletionHandler:completionHandler];
    if (processedByBraze) {
        return;
    }
    completionHandler(UIBackgroundFetchResultNoData);
}

//...//

- (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void (^)(void))completionHandler {
    BOOL processedByBraze = self.braze != nil && [self.braze.notifications handleUserNotificationWithResponse:response withCompletionHandler:completionHandler];
    if (processedByBraze) {
        return;
    }
    completionHandler();
}

- (void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler {
    if (@available(iOS 14.0, *)) {
        completionHandler(UNNotificationPresentationOptionList | UNNotificationPresentationOptionBanner);
    } else {
        completionHandler(UNNotificationPresentationOptionAlert);
    }
}

Location Tracking

The Braze kits for iOS and Android support Braze’s automatic location tracking features, provided that the appropriate app-level permissions are granted by the user.

Android

For Android push notifications you will need to provide your Server Key in your app settings page under Push Notification Settings.

iOS

For iOS push notifications you will need to upload your APNs Push SSL certificate to Braze. See the Braze documentation for more.

Special Considerations for mParticle A/B Testing With Braze and the mParticle SDK

mParticle supports the ability to conduct A/B testing with different integrations by sending a sample of users and their data to one integration and a different sample of users and their data to a different integration. If you are using the mParticle SDK for Braze deployment and calling Braze methods directly, when instrumenting with the mParticle SDK you must ensure that the Braze kit is active in the App before calling a Braze method. This is very important and ensures that you are not inadvertently calling Braze methods for apps/users that are not part of an Braze A/B sample.

Roku

mParticle supports the ability to forward server-side events for the Roku platform. Note that only data that includes your selected External Identity Type can be forwarded to Braze.

Data Processing Notes

mParticle will always forward events if sent via the mParticle SDK, provided you have included the Braze kit, but will only forward events sent via the mParticle S2S API if the following conditions apply:

1. The App Group REST API Key setting is specified.
2. Either your set External Identity Type, or a push token is specified.
3. Braze has limits on the number of characters in a property key - they must be less than or equal to 255 characters, with no leading dollar signs. When forwarding via a client-side kit, mParticle will remove the dollar sign ($) when forwarding property keys for user attributes, custom, and e-commerce events. When forwarding server-to-server, mParticle will remove the dollar sign ($) from mParticle reserved attributes.

Braze Instance

Braze maintains several instances. As part of the Configuration Settings, you need to specify which one your data should be forwarded to. You can tell your Braze Instance from the URL of your Braze Dashboard.

Check with your Braze account manager if you are unsure which Braze instance you are using.

There is also the ability to specify a Custom instance, which allows you to specify separate endpoints for REST, SDK and Javascript.

Prerequisites

In order to activate the Braze integration, you will need your Braze App Identifier API key and your “App Group REST API Key” if using the S2S API.

1. Sign into your Braze Account.
2. Click on Developer Console in the left navigation, then API Settings, Identification, and choose the Identifier for the platform you’re building to.
3. If you are sending data to mParticle via the S2S API, your “App Group REST API Key” value is required. Click on the Developer Console in the left navigation to get this value.

Event Data Mapping

Commerce Events

Depending on the setting value for Bundle Commerce Event Data (see Connection Settings for more), Commerce Events may be expanded based on the number of products, promotions, or impressions, respectively. Ex:

• If false, a single incoming event with 2 unique products/promotions/impressions would result in at least 2 outgoing Braze events.
• In true, a single incoming event with 2 unique products/promotions/impressions would result in 1 outgoing event with a nested products[], promotions[] or impressions[] array, respectively.

Product-based Commerce Events

Purchase Events

A purchase event is mapped and optionally-expanded to Braze purchase event(s) as described above.

In addition to the Common Commerce Fields, the following information is also captured, if defined:

Other Product-based Commerce Events

All other product-based commerce event types are mapped and optionally-expanded to Braze custom event(s) as described above. Note:

• If expansion is active and it’s a refund, an additional event representing the total is also generated.

As such, all relevant product and transaction information is conveyed via the properties field.

In addition to the Common Commerce Fields, the following information is also captured, if defined:

Common Product-based Commerce Fields

All product-based commerce events, regardless of type, capture these common fields in the properties dictionary in the following way:

Note: For web kit data, in order to forward the TransactionId, you must include the transactionAttributes as the fifth argument below. See our API docs for how to build transaction attributes.

mParticle.eCommerce.logProductAction(
    mParticle.ProductActionType.AddToCart,
    [product1, product2],
    customAttributes,
    customFlags, //can also be `null`, but can't be blank
    transactionAttributes);

Promotion-based Commerce Events

When promotions are expanded, each promotion is converted to its own outgoing Braze event. Alternatively, if expansion isn’t toggled, promotions are included in a nested collection in a single outgoing Braze event.

Impression-based Commerce Events

When impressions are expanded, each product from each impression is converted to its own outgoing Braze event. Alternatively, if expansion isn’t toggled, impressions and their associated products are included in a nested collection in a single outgoing Braze event.

Screen Views

Your screen view events will be passed to Braze using the screen name that you passed to our logScreen SDK method, as the event name.

If you are using automatic screen tracking in our Android SDK, the automatically-generated screen view events will be forwarded to Braze using the name of the associated Activity class.

Session Start / End

To send session start and end events for S2S to Braze, enable the Forward Session Events connection setting. After enabling this setting, session start and end events are forwarded to Braze as custom events with the names Session Start and Session End. When available, session IDs are also sent in the session_id property on all session starts and ends, screen view, and custom events.

However, note that mParticle SDK kits do not support session events, which are never forwarded with a kit, whether or not Forward Session Events is enabled.

Custom Events

All custom events will be forwarded to Braze using the event name that you passed to your logEvent SDK method. All event attributes will be forwarded to Braze as Braze custom event properties using the attribute names you passed to your logEvent SDK method as well.

Note: Braze documentation indicates that the following reserved keywords can’t be used as custom event properties:

• time
• event_name

To learn more, visit the Braze documentation:

• Android and FireOS
• iOS (legacy)
• Swift

User Attributes

The table below describes how the mParticle integration maps user attributes to Braze’s profile attributes.

Braze advises to coerce data types on user attributes shared with Braze before sending Production volume data. This ensures that the custom attributes received by Braze are of the expected data type. This can impact segment building and triggering campaigns. If incorrect data types are identified after data has been flowing, there can be extra work to true up the users with the legacy data type on those attributes. To give Braze’s type detection a better opportunity to evaluate data types properly, you can enable the following 2 Connection Settings: Enable API Custom Attribute Type Detection and Enable Kit Custom Attribute Type Detection.

Enriched Attributes and Identities

By default, mParticle forwards all available user attributes and user identities to Braze, including attributes added during profile enrichment. You can disable this behavior in the Connection Settings. Only data which is sent to Braze Server to Server can be enriched.

Subscription Groups

A User Attribute can be mapped to a Braze Subscription Group ID. Requests sent to mParticle containing the mapped User Attribute, with a valid true or false value, will determine if the user in the request should be subscribed (true) or unsubscribed (false) from the group. This allows for dynamic subscription management based on user attributes.

To configure Subscription Group Mapping:

1. Create the Subscription Group in Braze, if it doesn’t already exist.

2. Map the desired User Attribute to the Subscription Group ID in the mParticle dashboard.

   1. Note that the User Attribute must be sent to mParticle at least once before it is available for mapping.

3. Send the mapped User Attribute on your event batch to mParticle with a boolean value.

   1. true: User will be subscribed to the Braze Subscription Group.
   2. false: User will be unsubscribed from the Braze Subscription Group.
   3. Other non-boolean values will be ignored.

Subscription Group Errors

A misconfigured Subscription Group mapping can affect how your data is forwarded to Braze. If you notice your Subscription Groups are not being updated, check the following:

1. Invalid Subscription Group ID: Ensure the mapped Subscription Group IDs are correct in your Connection Settings.
2. Deleted Subscription Group: If a Subscription Group is deleted in Braze, you must update or remove the mapping in the mParticle dashboard.
3. Invalid User Attribute: Ensure the mapped User Attribute is being sent to mParticle with a boolean value.

Please note that Braze will only return an error in these cases when the Subscription Group attribute update is the only item in the request sent to Braze. If the request contains valid events and/or purchases, Braze will process these and skip the Subscription Group update. This also means that you will only see Subscription Group errors in the System Alerts page when the invalid Subscription Group update is the only item in the request.

Consent

Braze uses the $google_ad_user_data and $google_ad_personalization custom attribute keys to receive consent status for Google’s EU User Consent Policy. The Boolean sent to these keys signify that a user has granted or denied consent to a marketer. As per their Collecting consent for EEA, UK, and Switzerland end users documentation, this value must be sent to Google as a Custom Attribute.

User-specified Consent

To configure user consent forwarding under this value, a mapping should be set-up leveraging mParticle’s notion of Consent Purposes. To learn more about handling user consent within mParticle’s platform, see the following docs: Data Privacy Controls.

Once a Consent Purpose is set up, user consent information can be associated with it in subsequent Event Batches. The Consent Purpose data mapping can then be configured for downstream forwarding via the Consent Mapping connection setting.

Configuration Settings

Connection Settings

Braze Web Kit Critical Updates and Timelines

Braze occasionally makes breaking changes to their SDK, so if you call Braze directly in your code, you will have to update your code to ensure your website performs as expected when updating versions of Braze.

Opt In to Braze SDK Version 5

We recommend you use version 5 of the Braze SDK. You only need to make code changes if you directly call the Braze SDK from your code. Otherwise, you can simply select Version 5 from the mParticle connection settings.

If you are upgrading from V3, you should check the breaking changes from the Braze V4 Changelog as well as Braze V5 Changelog, in addition to the V4/5 migration guide to learn about the breaking changes. The most significant breaking changes are the replacement of the appboy class name with braze from V3 to V4, in addition to the removal and renaming of several APIs. If you are updating from V4 to V5, there are fewer changes, but you’d follow the same defensive code recommendations below.

You can opt into the latest major version of the Braze Web SDK whether you implement mParticle’s Web SDK using npm or our snippet/CDN.

• Customers who self-host mParticle via npm - You should add @mparticle/web-braze-kit version 5.0.0 or greater in your package.json. You must also select Version 5 under Braze Web SDK Version in the Braze connection settings.
• Customers who load mParticle via snippet/CDN - You must select Version 5 under Braze Web SDK Version in the Braze connection settings.

Note that the following is only one example, and demonstrates an upgrade from V3 to V5. Everywhere you manually call appboy (or other deprecated API) needs to be updated similar to the below. If you are using NPM, you can skip to step 4. Please be sure to test your site fully in development prior to releasing.

• Step 1: Legacy code sample. Find all the places where your code references the appboy.display namespace. Braze has removed all instances of the display namespace:

window.appboy.display.destroyFeed();

Step 2: Roll out code changes to be used before you opt in to using Version 4 of the Braze Web SDK so that it works under both versions:

if (window.appboy) {
    window.appboy.display.destroyFeed();
} else if (window.braze) {
    window.braze.destroyFeed();
}

Step 3: Whether you are using the snippet or self-hosting, you need to navigate to your Braze connection settings and select Version 5 from the Braze Web SDK Version drop down.

Step 4: After you opt in, you can simplify your code. We recommend testing and waiting at least 24 hours between opting in and removing previous instances of appboy and doing thorough testing of your application in a development environment to ensure everything is working:

window.braze.destroyFeed();

Step 4: Push Notifications via service-worker.js If you use Push Notifications, we have updated the service-worker.js file. In our testing, Braze’s push notifications work as expected regardless of what version of the service-worker is used, but we recommend updating this file to ensure future compatibility. In your service-worker.js file, update the code to reference https://static.mparticle.com/sdk/js/braze/service-worker-5.5.0.js instead of https://static.mparticle.com/sdk/js/braze/service-worker-3.5.0.js. Your service-worker.js file should now contain:

self.imports('https://static.mparticle.com/sdk/js/braze/service-worker-5.5.0.js')

Transition from @mparticle/web-appboy-kit to @mparticle/web-braze-kit

The legacy @mparticle/web-appboy-kit from npm includes version 2 of the Braze Web SDK. As part of this update, we’ve created a new Braze web kit repo to replace our deprecated Braze web kit repo. If you are still using @mparticle/web-appboy-kit, you will need to consider the breaking changes Braze made between V2 and V3 of the Braze SDK (found here) as well as the instructions above to get from V2 to V5 of the Braze SDK.