Remote Command: Braze

Requirements

• Braze API key
• One of the following mobile libraries:
  • Tealium for Android-Kotlin (1.0.0+)
  • Tealium for Android-Java (5.9.0+ for Braze 1.0.0+ or <5.9.0 for previous versions)
  • Tealium for iOS-Swift (2.8.0+)
• One of the following remote command integrations:
  • Braze Remote Command JSON File (Requires Android-Kotlin 1.0.0+ or iOS-Swift 2.1.0+)
  • Braze Remote Command tag in Tealium iQ Tag Management

How It Works

The Braze integration uses the following items:

1. The Braze native SDK.
2. The remote commands module that wraps the Braze methods.
3. Either the JSON configuration file or the Remote Command tag that translates event tracking into native Braze calls.

Adding the Braze remote command module to your app automatically installs and builds the required Braze libraries, without having to add vendor-specific code to your app. If you are using a dependency manager installation, there is no need to install the Braze SDK separately.

There are two remote command options: a JSON configuration file or using iQ Tag Management to configure the mappings. Using a JSON configuration file is recommended for your vendor integration, hosted either remotely or locally within your app. If using iQ Tag Management, add the Remote Command tag for the vendor integration. Learn more about vendor integrations.

Install

Dependency Manager

Manual Installation

Initialize

var tealium : Tealium?
let config = TealiumConfig(account: "ACCOUNT",
                           profile: "PROFILE",
                           environment: "ENVIRONMENT",
                           dataSource: "DATASOURCE")
config.dispatchers = [Dispatchers.TagManagement, Dispatchers.RemoteCommands]
config.remoteAPIEnabled = true // Required to use Remote Commands

tealium = Tealium(config: config) { _ in
    guard let remoteCommands = self.tealium?.remoteCommands else {
        return
    }

    // Webview Tag
    let braze = BrazeRemoteCommand(brazeLocation: BrazeLocationProvider()) 

    // Local JSON
    //let braze = BrazeRemoteCommand(type: .local(file: "braze"), brazeLocation: BrazeLocationProvider()) 

    // Remote JSON
    //let braze = BrazeRemoteCommand(type: .remote(url: "https://some.domain.com/braze.json"), brazeLocation: BrazeLocationProvider()) 

    remoteCommands.add(braze)
}

val config = TealiumConfig(application,
        "ACCOUNT",
        "PROFILE",
        Environment.DEV,
        dispatchers = mutableSetOf(Dispatchers.RemoteCommands, Dispatchers.TagManagement));
// New code to add the Braze Remote Command
val braze = BrazeRemoteCommand(application,
                            true,
                            sessionHandlingBlacklist,
                            true,
                            inAppMessageBlacklist)

var tealium = Tealium.create(TEALIUM_MAIN, config) {
    // Optional: Set config options that may not be supported yet by the Tag in Tealium IQ
    //              or simply to override settings locally.
    braze.registerConfigOverride { builder ->
        // builder.setIsLocationCollectionEnabled(true);
        // builder.setGeofencesEnabled(true);
        // builder.setPushDeepLinkBackStackActivityEnabled(true);
        // builder.setPushDeepLinkBackStackActivityClass(UserActivity.class);
    }

    // register the command

    // Webview Tag
    remoteCommands?.add(braze); 

    // Local JSON
    //remoteCommands?.add(braze, filename = "braze.json"); 

    // Remote JSON
    //remoteCommands?.add(braze, remoteUrl = "https://some.domain.com/braze.json"); 
}

import com.tealium.remotecommands.BrazeRemoteCommand;

Tealium.Config config = Tealium.Config.create(application, "ACCOUNT", "PROFILE", "ENVIRONMENT");
Tealium teal = Tealium.createInstance(TEALIUM_MAIN, config);

BrazeRemoteCommand braze;
// Initialize with default configuration options.
braze = new BrazeRemoteCommand(config);

// Or alternatively initialize with some additional config options:
Set<Class> sessionHandlingBlacklist = new HashSet<>();
Set<Class> inAppMessageBlacklist = new HashSet<>();
// sessionHandlingBlacklist.add(MainActivity.class);
// inAppMessageBlacklist.add(UserActivity.class);
braze = new BrazeRemoteCommand(config,
        true,                     // sessiongHandlingEnabled
        sessionHandlingBlacklist, // sessionHandlingBlacklist
        true,                     // registerInAppMessageManager
        inAppMessageBlacklist);   // inAppMessageBlackList

// Optional: Set config options that may not be supported yet by the Tag in Tealium IQ
//              or simply to override settings locally.
braze.registerConfigOverride(new BrazeRemoteCommand.ConfigOverrider() {
    @Override
    public void onOverride(AppboyConfig.Builder b) {
        b.setPushDeepLinkBackStackActivityEnabled(true);
        b.setPushDeepLinkBackStackActivityClass(UserActivity.class);
    }
});

// register the command
teal.addRemoteCommand(braze);

import BrazeRemoteCommand from 'tealium-react-braze';
BrazeRemoteCommand.initialize();

// Webview Tag
let braze = { id: BrazeRemoteCommand.name } 

// Local JSON
//let braze = { id: BrazeRemoteCommand.name, path: "braze.json" } 

// Remote JSON
//let braze = { id: BrazeRemoteCommand.name, url: "https://some.domain.com/braze.json" } 

let config = TealiumConfig {
    // ...
    remoteCommands: [braze]
}

JSON Template

If you are configuring remote commands using a JSON configuration file, refer to the following template to get started. The template includes common mappings used in a standard e-commerce installation. Edit the mappings as needed.

{
    "config": {
        "api_key": "YOUR_API_KEY",
        "custom_endpoint": "sdk.iad-01.braze.com",
        "session_timeout": 30,
        "trigger_interval_seconds": 100,
        "enable_geofences": true,
        "enable_automatic_geofences": true,
        "enable_automatic_location": true,
        "push_story_identifier": "YOUR_IDENTIFIER",
        "use_uuid_as_device_id": true,
        "forward_universal_links": true
    },
    "mappings": {
        "customer_id": "user_id",
        "customer_first_name": "first_name",
        "customer_last_name": "last_name",
        "customer_gender": "gender",
        "customer_language": "language",
        "customer_email": "email",
        "customer_home_city": "home_city",
        "customer_dob": "date_of_birth",
        "customer_alias": "user_alias",
        "customer_alias_label": "alias_label",
        "pet": "set_custom_attribute.pet",
        "pet_count": "set_custom_attribute.pet_count",
        "pet_count_unset": "unset_custom_attribute.pet_count_unset",
        "pet_count_increment": "increment_custom_attribute.pet_count_increment",
        "pet_names": "set_custom_array_attribute.pet_names",
        "pet_names_append": "append_custom_array_attribute.pet_names_append",
        "pet_names_remove": "remove_custom_array_attribute.pet_names_remove",
        "screen_name": "screen_name",
        "email_notification": "email_notification",
        "push_notification": "push_notification",
        "event_name": "event_name",
        "current_level": "event.current_level",
        "start_date": "event.start_date",
        "high_score": "event.high_score",
        "product_id": "product_id",
        "product_quantity": "product_qty",
        "product_unit_price": "product_unit_price",
        "currency_code": "product_currency",
        "rewards_member": "purchase.rewards_member",
        "rewards_points_earned": "purchase.rewards_points_earned",
        "date_joined_program": "purchase.date_joined_program",
        "latitude": "location_latitude",
        "longitude": "location_longitude",
        "horizontal_accuracy": "location_horizontal_accuracy",
        "vertical_accuracy": "location_vertical_accuracy"
    },
    "commands": {
        "launch": "initialize",
        "setengagement": "emailnotification,pushnotification",
        "log_custom_event": "logcustomevent",
        "set_location": "setlastknownlocation",
        "custom_attribute": "setcustomattribute",
        "unset_custom_attribute": "unsetcustomattribute",
        "custom_array_attribute": "appendcustomarrayattribute",
        "append_custom_array_attribute": "appendcustomarrayattribute",
        "remove_custom_array_attribute": "removecustomarrayattribute",
        "increment_custom_attribute": "incrementcustomattribute",
        "log_purchase": "logpurchase",
        "user_attribute": "userattribute,useridentifier,useralias",
        "user_login": "useridentifier,useralias",
        "user_alias": "useralias",
    }
}

Supported Methods

We map a command to each Braze method. To trigger a Braze method, pass the corresponding command in the specified format.

Since the Braze SDK is installed alongside the Tealium SDK, trigger any native Braze functionality given the corresponding tag configuration.

SDK Setup

Initialize

The Braze API key and the custom endpoint are required and need to be set in the tag configuration.

The following mappings are used to set launch options.

Android

• Braze Developer Guide: Initial SDK Setup

iOS

• Braze Developer Guide: Initial SDK Setup
• Braze Developer Guide: Fine Network Traffic Control
• Braze Developer Guide: Locations and Geofences
• Braze Developer Guide: Push Story Setup
• Braze Developer Guide: Tracking Sessions

Set SDK Auth Signature

Flush

• Braze Developer Guide: Analytics Disabling
  • iOS

User Tracking

Assigning a User ID

• Braze Developer Guide: Analytics User IDs
  • iOS
  • Android

Aliasing Users

• Braze Developer Guide: Analytics Alias Users
  • iOS
  • Android

User Attributes

Standard Attributes

• Braze Developer Guide: Analytics User Attributes
  • iOS
  • Android
• Braze Developer Guide: User Data API

Set Custom Attribute

• Braze Developer Guide: Analytics Custom Attributes
  • iOS
  • Android

Unset Custom Attribute

• Braze Developer Guide: Analytics Custom Attributes
  • iOS
  • Android

Increment Custom Attribute

• Braze Developer Guide: Analytics Incrementing Attributes
  • iOS
  • Android

Set Custom Array Attribute

• Braze Developer Guide: Analytics Array Attributes
  • iOS
  • Android

Append Custom Array Attribute

• Braze Developer Guide: Analytics Array Attributes
  • iOS
  • Android

Remove Custom Array Attribute

• Braze Developer Guide: Analytics Array Attributes
  • iOS
  • Android

Custom Event Tracking

Custom Event

• Braze Developer Guide: Analytics Custom Events
  • iOS
  • Android

Notifications

Email Notifications

• Braze Developer Guide: Analytics Email Subscriptions
  • iOS
  • Android

Add to subscription group

• Braze Developer Guide: Subscription Groups

Remove from subscription group

• Braze Developer Guide: Subscription Groups

Push Notifications

• Braze Developer Guide: Analytics Push Notifications
  • iOS
  • Android

Purchase Tracking

Log Purchase

• Braze Developer Guide: Analytics Purchase Events
  • iOS
  • Android

Location Tracking

Set User’s Last Known Location

• Braze Developer Guide: Analytics Location Tracking

Data Privacy (Consent Options)

Enable SDK

• Braze Developer Guide: Analytics Disabling
  • iOS
  • Android

Disable SDK

• Braze Developer Guide: Analytics Disabling
  • iOS
  • Android

Wipe Data

• Braze Developer Guide: Analytics Disabling
  • iOS
  • Android

Set Ad Tracking Enabled

Accessing the Braze instance (iOS)

The remote command offers a convenient way to map some of the functionality offered by Braze into your app, such as logging of events and purchases. However, some Braze features, such as content cards, feature flags, or notifications, have to be integrated into your app using the Braze instance.

To access the Braze instance directly, use the onReady method. The onReady method returns the Braze instance in the completion block once it’s properly configured.

brazeRemoteCommand.onReady { braze in
    // use the Braze instance here
}

Once you have a reference to the Braze instance, use it as described in the Braze documentation.

Automatic push integration

The latest Braze version supports a way to automate the processing of remote notifications. For more information, see Braze Developer Guide: Automatic push integration.

To use this feature the Braze instance must be initialized synchronously on the main thread in the didFinishLaunchingWithOptions method of the app delegate. This means you must configure the Braze instance directly instead of using our remote command configuration.

To configure the Braze instance directly, use this code:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    let brazeConfig = Braze.Configuration(apiKey: "YOUR_API_KEY", endpoint: "YOUR_ENDPOINT")
    brazeConfig.push.automation = true
    // ...
    // add all your other configuration here
    // ...
    let brazeInstanceWrapper = BrazeInstance()
    brazeInstanceWrapper.initializeBraze(brazeConfig: brazeConfig)
    let brazeCommand = BrazeRemoteCommand(brazeInstance: brazeInstanceWrapper)
    let tealiumConfig = TealiumConfig(...)
    tealiumConfig.remoteCommands = [brazeCommand]
    // ... 
    // complete tealium initialization
    return true
}

Manual push integration

To implement the manual push integration, keep the remote command configuration and enable the push integration directly by accessing the Braze instance.

For more information, see Braze Developer Guide: Manual push integration.