Remote Command: Branch

Tealium remote command integration for Branch on Android and Swift/iOS.

Requirements

How It Works

The Branch integration uses three items:

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

Adding the Branch remote command module to your app automatically installs and builds the required Branch 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 Branch 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.

  1. In your Xcode project, select File > Add Packages… > Add Package Dependency.
  2. Enter the repository URL: https://github.com/tealium/tealium-ios-branch-remote-command.
  3. Configure the version rules. Typically, Up to next major is recommended. If the current TealiumBranch version does not appear in the list, then reset your Swift package cache.
  4. Select the TealiumBranch module to install, and select the app target you want the module to be installed in.

If your project has more than one app target and needs TealiumBranch module in more app targets, you have to manually add them in the Frameworks, Libraries, and Embedded Content section.

To install TealiumBranch in additional app targets:

  1. Select your Xcode project in the Project Navigator.
  2. In your Xcode project, select the app target under the TARGETS section.
  3. Navigate to General > Frameworks, Libraries & Embedded Content and select the TealiumBranch module to add it to your app target.

To add additional modules from the Tealium Swift library, follow the Swift Package Manager instructions.

  1. Remove tealium-swift and pod "Branch" if they already exist your Podfile. The dependency for tealium-swift is already included in the TealiumBranch framework.

  2. Add the following dependency to your Podfile:

    pod "TealiumBranch"
    

    The TealiumBranch pod includes the following TealiumSwift dependencies:

    'tealium-swift/Core'
    'tealium-swift/RemoteCommands'
    'tealium-swift/TagManagement'
    
  3. Import the modules TealiumSwift and TealiumBranch in your TealiumHelper file, and any other files that access the Tealium class, or the Branch Remote Command.

  1. Remove tealium-swift from your Cartfile. The dependency for tealium-swift is already included in the TealiumBranch framework.

  2. Add the following dependency to your Cartfile:

    github "tealium/tealium-ios-branch-remote-command"
    

Tealium for Swift SDK (version 1.6.5+) requires the TealiumDelegate module to be included with your installation.

  1. Install Tealium for Android (Kotlin) or Tealium for Android (Java), if you haven’t done so already.

  2. Add the Tealium Maven URL to your project’s top-level build.gradle file:

    allprojects {
      repositories {
        jcenter()
        maven {
          url "https://maven.tealiumiq.com/android/releases/"
        }
      }
    }
    
  3. Import both the Branch SDK and Tealium-Branch remote commands by adding the following dependencies in your app project’s build.gradle file:

    dependencies {
          implementation 'com.tealium.remotecommands:branch:1.0.0'
    }
    

Manual Installation

The manual installation for Branch remote commands requires the Tealium for Swift library to be installed. To install the Branch remote commands for your iOS project:

  1. Install the Branch SDK, if you haven’t already done so.

  2. Clone the Tealium iOS Branch remote command repo and drag the files within the Sources folder into your project.
    GitHub repo: https://github.com/tealium/tealium-ios-branch-remote-command

  3. Set the remoteAPIEnabled configuration flag to true.

The manual installation for Branch remote commands requires Tealium for Android (Kotlin) or Tealium for Android (Java) to be installed.

To install the Branch remote commands for your Android project:

  1. Add flatDir to your project root build.gradle file:

    allprojects {
          repositories {
            jcenter()
            flatDir {
                dirs 'libs'
            }
          }
    }
    
  2. Add tealium-branch.aar to <PROJECT_ROOT>/<MODULE>/libs.

  3. Add the Tealium library dependency to your build.gradle file:

    dependencies {
          implementation(name:'tealium-branch', ext:'aar')
    }
    

Initialize

For all Tealium libraries, register the Branch mobile remote commands when you initialize.

Initialize remote commands with a JSON configuration file or the Remote Command tag for Tealium’s iOS (Swift) library:

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 branch = BranchRemoteCommand() 

    // Local JSON
    //let branch = BranchRemoteCommand(type: .local(file: "branch")) 

    // Remote JSON
    //let branch = BranchRemoteCommand(type: .remote(url: "https://some.domain.com/branch.json")) 

    remoteCommands.add(branch)
}

Initialize remote commands with a JSON configuration file or the Remote Command tag for Tealium’s Kotlin library:

val config = TealiumConfig(application,
        "ACCOUNT",
        "PROFILE",
        Environment.DEV,
        dispatchers = mutableSetOf(Dispatchers.RemoteCommands, Dispatchers.TagManagement));
val branch = BranchRemoteCommand(application);

var tealium = Tealium.create(TEALIUM_MAIN, config) {

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

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

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

Initialize remote commands with the Remote Command tag for Tealium’s Android (Java) library:

RemoteCommand branch = new BranchRemoteCommand(application);
teal.addRemoteCommand(branch);

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 installation. Edit the mappings as needed.

{
  "config": {
    "settings": {
      "enable_logging": true,
      "branch_dev_key": "branch_key",
      "collect_device_id": true
    }
  },
  "mappings": {
    "tealium_event": "event.description",
    "description": "buo.description",
    "item_id": "buo.canonical_identifier",
    "title": "buo.title",
    "feature": "link.feature",
    "channel": "link.channel",
    "campaign": "link.campaign",
    "latitude": "metadata.latitude",
    "longitude": "metadata.longitude",
    "currency_code": "metadata.currency_type",
    "customer_id": "event.user_id",
    "coupon": "metadata.coupon",
    "product_brand": "metadata.product_brand",
    "product_category": "metadata.product_category",
    "product_id": "metadata.sku",
    "product_name": "metadata.product_name",
    "product_variant": "metadata.product_variant",
    "product_unit_price": "metadata.price",
    "product_quantity": "event.quantity",
    "currency_type": "event.currency",
    "order_tax": "event.tax"
  },
  "commands": {
    "launch": "initialize",
    "user_login": "login,setuserid",
    "user_register": "completeregistration",
    "show_offers": "clickad",
    "cart_add": "addtocart",
    "wishlist_add": "addtowishlist",
    "payment": "addpaymentinfo",
    "level_up": "achievelevel",
    "email_signup": "subscribe",
    "product": "viewitem",
    "share": "share",
    "rate": "rate",
    "search": "search",
    "invite": "invite",
    "order": "initiatepurchase",
    "record_score": "record_score",
    "teal_custom_event": "teal_custom_event"
  }
}

Supported Methods

The following Branch methods are triggered using a data mapping in the Branch Remote Command tag using the following Tealium commands:

iOS Remote Commands

iOS Remote Command Branch Method
initialize initSession()
setuserid setIdentity()
logout logout()
Any other logEvent()

Android Remote Commands

Android Remote Command Branch Method
initialize initSession()
setuserid setIdentity()
logout logout()
createdeeplink generateShortUrl()
Any other logEvent()

Standard Event Names

The following standard event command names are supported with the logEvent method. When a command is sent, and all required variables are mapped and defined for the event, then the command is automatically triggered in the Branch SDK.

Remote Command Branch Event Name (iOS) Branch Event Name (Andriod)
achievelevel BranchStandardEvent.achieveLevel BRANCH_STANDARD_EVENT.ACHIEVE_LEVEL
addpaymentinfo BranchStandardEvent.addPaymentInfo BRANCH_STANDARD_EVENT.ADD_PAYMENT_INFO
addtocart BranchStandardEvent.addToCart BRANCH_STANDARD_EVENT.ADD_TO_CART
addtowishlist BranchStandardEvent.addToWishlist BRANCH_STANDARD_EVENT.ADD_TO_WISHLIST
clickad BranchStandardEvent.clickAd BRANCH_STANDARD_EVENT.CLICK_AD
completetutorial BranchStandardEvent.completeTutorial BRANCH_STANDARD_EVENT.COMPLETE_TUTORIAL
completeregistration BranchStandardEvent.completeRegistration BRANCH_STANDARD_EVENT.COMPLETE_REGISTRATION
completestream Custom event BranchEvent(eventName) BRANCH_STANDARD_EVENT.COMPLETE_STREAM
initiatepurchase BranchStandardEvent.initiatePurchase BRANCH_STANDARD_EVENT.INITIATE_PURCHASE
initiatestream Custom event BranchEvent(eventName) BRANCH_STANDARD_EVENT.INITIATE_STREAM
invite BranchStandardEvent.invite BRANCH_STANDARD_EVENT.INVITE
login BranchStandardEvent.login BRANCH_STANDARD_EVENT.LOGIN
purchase BranchStandardEvent.purchase BRANCH_STANDARD_EVENT.PURCHASE
rate BranchStandardEvent.rate BRANCH_STANDARD_EVENT.RATE
reserve BranchStandardEvent.reserve BRANCH_STANDARD_EVENT.RESERVE
search BranchStandardEvent.search BRANCH_STANDARD_EVENT.SEARCH
share BranchStandardEvent.share BRANCH_STANDARD_EVENT.SHARE
spendcredits BranchStandardEvent.spendCredits BRANCH_STANDARD_EVENT.SPEND_CREDITS
starttrial BranchStandardEvent.startTrial BRANCH_STANDARD_EVENT.START_TRIAL
subscribe BranchStandardEvent.subscribe BRANCH_STANDARD_EVENT.SUBSCRIBE
unlockachievement BranchStandardEvent.unlockAchievement BRANCH_STANDARD_EVENT.UNLOCK_ACHIEVEMENT
viewad BranchStandardEvent.viewAd BRANCH_STANDARD_EVENT.VIEW_AD
viewcart BranchStandardEvent.viewCart BRANCH_STANDARD_EVENT.VIEW_CART
viewitem BranchStandardEvent.viewItem BRANCH_STANDARD_EVENT.VIEW_ITEM
viewitems BranchStandardEvent.viewItems BRANCH_STANDARD_EVENT.VIEW_ITEMS
custom BranchEvent(eventString) BranchEvent(eventString)

SDK Setup

Learn more about the Branch SDK Setup:

Initialize

The Branch SDK is initialized automatically upon launch. The Branch Key is set in the Info.plist or the branch_dev_key inside the JSON configuration file.

Remote Command Branch Method
initialize initSession()

There are a few configuration options available for the Branch Remote Command tag. If any of the below are set on launch, they are sent during the configure() method.

Configuration Options
Name TiQ Variable Mapping Description Type
Enable Logging enable_logging Log Branch events to the console Bool
Branch Key branch_dev_key The key for your branch application. String
Remote Command Branch Method
setIdentity setIdentity()
Parameter Type
id (required) String

Was this page helpful?

This page was last updated: January 26, 2023