Remote Command: Braze
Requirements
- Braze API key
- One of these 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
- One of these 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 three items:
- The Braze native SDK
- The remote commands module that wraps the Braze methods
- Either the JSON configuration file or 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. A JSON configuration file is the recommended option 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
We recommend using one of the following dependency managers for installation:
If you are using the Tealium iOS (Objective-C) library, use the manual installation method. The CocoaPods and Carthage options are only available if you are using the Tealium iOS (Swift) library.
To install Braze remote commands for iOS using CocoaPods:
Remove
tealium-swift
andpod "Appboy-iOS-SDK"
if they exist in your Podfile. The dependency fortealium-swift
is already included in theTealiumBraze
framework.Add the following dependency to your Podfile:
pod "TealiumBraze"
The
TealiumBraze
pod includes the followingTealiumSwift
dependencies:'tealium-swift/Core' 'tealium-swift/RemoteCommands' 'tealium-swift/TagManagement'
Import the modules
TealiumSwift
andTealiumBraze
in yourTealiumHelper
file, and any other files that access theTealium
class, or the Braze remote command.
To install Braze remote commands for iOS using Carthage:
Remove
tealium-swift
from your Cartfile. The dependency fortealium-swift
is already included in theTealiumBraze
framework.Remove the following line if it exists in your Cartfile:
github "Appboy/Appboy-iOS-SDK"
Add the following dependency to your Cartfile:
github "tealium/tealium-ios-braze-remote-command"
Tealium for Swift SDK (version 1.x) and TealiumBraze
version 1.x requires the TealiumDelegate
module to be included with your installation.
To install Braze remote commands for Android using Maven:
Install Tealium for Android (Kotlin) or Tealium for Android (Java) and add the Tealium Maven URL to your project’s top-level
build.gradle
file, if you haven’t done so already.allprojects { repositories { jcenter() maven { url "https://maven.tealiumiq.com/android/releases/" } } }
Import both the Braze SDK and Tealium-Braze remote commands by adding the following dependencies in your app project’s
build.gradle
file:dependencies { implementation 'com.tealium.remotecommands:braze:1.0.0' implementation 'com.appboy:android-sdk-ui:10.1.0' }
Manual (iOS)
The manual installation for Braze remote commands requires the Tealium for Swift library to be installed. To install the Braze remote commands for your iOS project:
Install the Braze SDK, if you haven’t already done so.
Clone the Tealium iOS Braze remote command repo and drag the files within the
Sources
folder into your project.Set the
remoteAPIEnabled
configuration flag totrue
Initialize
For all Tealium libraries, you need to register the Braze remote command when you initialize.
Android (Kotlin)
Initialize remote commands with a JSON configuration file or the Remote Command tag for Tealium’s Kotlin library.
The following code is designed for use with the JSON Remote Commands feature, using the local file option:
val config = TealiumConfig(application,
"ACCOUNT",
"PROFILE",
Environment.DEV,
dispatchers = mutableSetOf(Dispatchers.RemoteCommands));
// New code to add the Braze Remote Command
val brazeRemoteCommand = 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.
brazeRemoteCommand.registerConfigOverride { builder ->
// builder.setIsLocationCollectionEnabled(true);
// builder.setGeofencesEnabled(true);
// builder.setPushDeepLinkBackStackActivityEnabled(true);
// builder.setPushDeepLinkBackStackActivityClass(UserActivity.class);
}
// register the command
remoteCommands?.add(brazeRemoteCommand, filename = "braze.json");
}
The following code is designed for use with the Remote Command tag feature:
val config = TealiumConfig(application,
"ACCOUNT",
"PROFILE",
Environment.DEV,
dispatchers = mutableSetOf(Dispatchers.RemoteCommands, Dispatchers.TagManagement));
// New code to add the Braze Remote Command
val brazeRemoteCommand = 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.
brazeRemoteCommand.registerConfigOverride { builder ->
// builder.setIsLocationCollectionEnabled(true);
// builder.setGeofencesEnabled(true);
// builder.setPushDeepLinkBackStackActivityEnabled(true);
// builder.setPushDeepLinkBackStackActivityClass(UserActivity.class);
}
// register the command
remoteCommands?.add(brazeRemoteCommand);
}
Android (Java)
The JSON Remote Command file feature for Android is only available in the Kotlin SDK.
The following code is designed for use with the Remote Command tag feature:
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);
iOS (Swift)
Initialize remote commands with a JSON configuration file or the Remote Command tag for Tealium’s iOS (Swift) library.
The following code is designed for use with the JSON Remote Commands feature, using the local file option:
var tealium : Tealium?
let config = TealiumConfig(account: "ACCOUNT",
profile: "PROFILE",
environment: "ENVIRONMENT",
dataSource: "DATASOURCE",
optionalData: nil)
config.remoteAPIEnabled = true // Required to use Remote Commands
tealium = Tealium(config: config) { _ in
guard let remoteCommands = self.tealium?.remoteCommands else {
return
}
let braze = BrazeRemoteCommand(type: .local(file: "braze"))
remoteCommands.add(braze)
}
The following code is designed for use with the Remote Command tag feature:
var tealium : Tealium?
let config = TealiumConfig(account: "ACCOUNT",
profile: "PROFILE",
environment: "ENVIRONMENT",
dataSource: "DATASOURCE",
optionalData: nil)
config.remoteAPIEnabled = true // Required to use Remote Commands
tealium = Tealium(config: config) { _ in
guard let remoteCommands = self.tealium?.remoteCommands else {
return
}
let braze = BrazeRemoteCommand()
remoteCommands.add(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",
"session_timeout": 30,
"disable_location": false,
"trigger_interval_seconds": 100
},
"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",
"facebook_user": "facebook_user",
"number_of_friends": "friends_count",
"list_of_likes": "likes",
"facebook_user_properties": "facebook_user",
"social_media_user_description": "description",
"twitter_id": "twitter_id",
"twitter_name": "twitter_name",
"twitter_user_description": "description",
"profile_image_url": "profile_image_url",
"screen_name": "screen_name",
"number_of_followers": "followers_count",
"number_of_statuses": "statuses_count",
"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": "quantity",
"product_unit_price": "product_unit_price",
"currency_code": "order_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"
},
"commands": {
"launch": "initialize",
"twitter": "twitteruser",
"facebook": "facebookuser",
"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
The following Braze methods are triggered using a data mapping in the Braze Remote Command tag using the following Tealium commands:
Remote Command | Braze Method |
---|---|
appendcustomarrayattribute |
addToCustomAttributeArrayWithKey() |
emailnotification |
setEmailNotificationSubscriptionType() |
facebookuser |
facebookUser() |
incrementcustomattribute |
incrementCustomUserAttribute() |
initialize |
startWithApiKey() |
logcustomevent |
logCustomEvent() |
logpurchase |
logPurchase() |
pushnotification |
setPushNotificationSubscriptionType() |
removecustomarrayattribute |
removeFromCustomAttributeArrayWithKey() |
setcustomattribute |
setCustomAttributeWithKey() |
setcustomarrayattribute |
setCustomAttributeArrayWithKey() |
setlastknownlocation |
setLastKnownLocationWithLatitude() |
twitteruser |
twitterUser() |
unsetcustomattribute |
unsetCustomAttributeWithKey() |
useralias |
addAlias() |
userattribute |
ABKUser() |
useridentifier |
changeUser() |
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 SDK is initialized automatically upon launch. The Braze API key is set in the tag configuration.
Remote Command | Braze Method (iOS) | Braze Method (Android) |
---|---|---|
initialize |
startWithApiKey() |
configure() |
The following mappings are used to set launch options.
Parameter | Type | Description |
---|---|---|
custom_endpoint |
String |
Sets a custom API endpoint. This gets sent in the format sdk.api.braze.eu |
device_options |
Int |
Key to specify a whitelist for device fields that are collected by the Braze SDK (default all fields are collected) |
disable_location |
Int |
Disable automatic location data collection (1 or 0 ) |
enable_geofences |
Int |
Enable automatic collection of geofences (1 or 0 ) |
flush_interval |
Double |
Sets the data flush interval (in seconds). Values are converted into NSTimeIntervals and must be greater than 1.0 |
push_story_identifier |
String |
This key is set to a string value representing the app group name for the Push Story Notification Content extension. |
request_processing_policy |
Int |
Possible values for the SDKs request processing (default ABKAutomaticRequestProcessing) |
session_timeout |
Int (seconds) |
The session timeout in seconds (default: 30 seconds) |
trigger_interval_seconds |
Int (seconds) |
Override the minimum interval between in-app message triggers (default: 30 seconds) |
Android
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
User Tracking
Assigning a User ID
Remote Command | Braze Method |
---|---|
useridentifier |
changeUser |
Parameter | Type |
---|---|
user_id (required) |
String |
Aliasing Users
Remote Command | Braze Method |
---|---|
useralias |
addAlias |
Parameter | Type |
---|---|
user_alias (required) |
String |
alias_label (required) |
String |
User Attributes
Standard Attributes
Event | Braze Method |
---|---|
userattribute | Set fields on the ABKUser/AppboyUser object |
Parameter | Type |
---|---|
first_name |
String |
last_name |
String |
email |
String |
date_of_birth |
String |
country |
String |
language |
String |
home_city |
String |
phone |
String |
avatar_image_url |
String |
gender |
String |
- Braze Developer Guide: Analytics User Attributes
- Braze Developer Guide: User Data API
Set Custom Attribute
Remote Command | Braze Method (iOS) | Braze Method (Android) |
---|---|---|
setcustomattribute |
setCustomAttributeWithKey |
setCustomUserAttribute |
Parameter | Type |
---|---|
set_custom_attribute.PROPERTY |
[String: Any] / JSONObject |
Unset Custom Attribute
Remote Command | Braze Method (iOS) | Braze Method (Android) |
---|---|---|
setcustomattribute |
unsetCustomAttributeWithKey |
unsetCustomUserAttribute |
Parameter | Type |
---|---|
set_custom_attribute.PROPERTY |
String |
Increment Custom Attribute
Remote Command | Braze Method |
---|---|
incrementcustomattribute |
incrementCustomUserAttribute |
Parameter | Type |
---|---|
increment_custom_attribute.PROPERTY |
String |
Set Custom Array Attribute
Remote Command | Braze Method (iOS) | Braze Method (Android) |
---|---|---|
setcustomarrayattribute | setCustomAttributeArrayWithKey |
setCustomAttributeArray |
Parameter | Type |
---|---|
set_custom_array_attribute.PROPERTY |
[String: [Any]] / JSONObject |
Append Custom Array Attribute
Remote Command | Braze Method (iOS) | Braze Method (Android) |
---|---|---|
appendcustomarrayattribute |
addToCustomAttributeArrayWithKey |
addToCustomAttributeArray |
Parameter | Type |
---|---|
append_custom_array_attribute.PROPERTY |
[String: String] / JSONObject |
Remove Custom Array Attribute
Remote Command | Braze Method (iOS) | Braze Method (Android) |
---|---|---|
removecustomarrayattribute | removeFromCustomAttributeArrayWithKey |
removeFromCustomAttributeArray |
Parameter | Type |
---|---|
remove_custom_array_attribute.PROPERTY |
[String: String] / JSONObject |
Social Data Tracking
Remote Command | Braze Method |
---|---|
facebookuser |
Initialize an ABKFacebookUser/FacebookUser object |
Parameter | Type |
---|---|
facebook_id |
[String: Any] / String |
friends_count |
Int |
likes |
[Any] / String[] |
Remote Command | Braze Method |
---|---|
twitteruser |
Initialize a ABKTwitterUser/TwitterUser object |
Parameter | Type |
---|---|
description |
String |
twitter_name |
String |
profile_image_url |
String |
screen_name |
String |
followers_count |
Int |
friends_count |
Int |
statuses_count |
Int |
twitter_id |
Int |
Custom Event Tracking
Custom Event
Remote Command | Braze Method |
---|---|
logcustomevent |
logCustomEvent |
Parameter | Type |
---|---|
event_name (required) |
String |
event_properties |
[String: Any] / JSONObject |
Notifications
Email Notifications
Remote Command | Braze Method |
---|---|
emailnotification |
setEmailNotificationSubscriptionType |
Parameter | Type | Example |
---|---|---|
email_notification |
String |
["optedin" , "subscribed" , "unsubscribed" ] |
Push Notifications
Remote Command | Braze Method |
---|---|
pushnotification | setPushNotificationSubscriptionType |
Parameter | Type | Example |
---|---|---|
push_notification |
String |
["optedin" , "subscribed" , "unsubscribed" ] |
Purchase Tracking
Log Purchase
Remote Command | Braze Method |
---|---|
logpurchase | logPurchase |
Parameter | Type |
---|---|
product_id (required) |
[String] / String[] |
currency (required) |
String / String |
price (required) |
[Double] / Double[] |
quantity |
[Int] / Int[] |
purchase_properties |
[AnyHashable: Any] / JSONObject |
Location Tracking
Set User’s Last Known Location
Remote Command | Braze Method |
---|---|
setlastknownlocation |
setLastKnownLocationWithLatitude |
Parameter | Type |
---|---|
latitude (required) |
Double |
longitude (required) |
Double |
horizontalAccuracy (required) |
Double |
altitude |
Double |
verticalAccuracy |
Double |
Data Privacy
Enable SDK
Remote Command | Braze Method (iOS) | Braze Method (Android) |
---|---|---|
enable_sdk |
enableSDK |
enableSdk/disableSdk |
Parameter | Type | Example |
---|---|---|
enable_sdk |
Boolean |
true / false |
Wipe Data
Remote Command | Braze Method |
---|---|
wipe_data |
wipeData |
Was this article helpful?
This page was last updated: March 2, 2022