• Platforms
  • Partners
  • Forums
  • 日本語
  • TLC Tealium Learning Center Tealium Learning
    Community
  • Discussions & Ideas Dicussions & Ideas
  • Product Guides Product Guides
  • Knowledge Base Knowledge Base
  • Developer Docs Developer Docs
  • Education Education
  • TLC Blog TLC Blog
  • Support Desk Support Desk
  • CDH Customer Data Hub Customer Data Hub
  • Mobile
  • Getting Started
    • Overview
    • Quick Start Guide
    • Mobile Concepts
    • Client-Side
    • Server-Side
    • Tracking Webviews
    • Data Layer
    • Consent Management
    • Event Batching
    • User Location and Geofencing
    • Media Tracking
    • Deep Links
    • Timed Events
    • Trace
    • Hosted Data Layer
    • Adobe Visitor Service Module
    • Feature Comparison
    • Troubleshooting
  • Remote Commands
    • Overview
    • How It Works
    • Integrations
      • Adjust
      • AppsFlyer
      • Branch
      • Braze
      • Contentsquare
      • Facebook
      • Firebase
      • Kochava
      • Usabilla
  • Android (Java)
    • Overview
    • Install
    • Track
    • Data Layer
    • Data Management
    • Consent Management
    • Module List
      • Ad Identifier Module
      • Crash Reporter Module
      • Install Referrer Module
      • Lifecycle Tracking Module
      • Location Module
      • Optimizely X Tracking Module
    • Android TV
    • Android Wear
    • API Reference
      • ConsentManager
      • DataSources
      • Lifecycle
      • Tealium
      • Tealium.Config
      • TealiumLocation
    • Release Notes
  • Android (Kotlin)
    • Overview
    • Install
    • Track
    • Data Layer
    • Consent Management
    • Identity Resolution
    • Module List
      • Ad Identifier Module
      • AutoTracking Module
      • AdobeVisitorService Module
      • Collect Module
      • Collectors Module
      • Crash Reporter Module
      • In-App Purchase Module
      • Install Referrer Module
      • Lifecycle Tracking Module
      • Location Manager Module
      • Media Module
      • RemoteCommands Module
      • Tag Management Dispatcher Module
      • Visitor Service Module
    • Android TV
    • API Reference
      • ConsentCategory
      • ConsentManager
      • CurrentVisit
      • DataLayer
      • Lifecycle
      • LocationManager
      • Media
      • Tealium
      • TealiumConfig
      • VisitorProfile
      • VisitorService
    • Release Notes
  • Cordova 1.x
    • Overview
    • Install
    • Track
    • Data Management
    • Module List
      • Ad Identifier Module
      • Crash Reporter Module
      • Install Referrer Module
    • API Reference
    • Release Notes
  • Cordova 2.x
    • Overview
    • Install
    • Track
    • API Reference
    • Release Notes
  • Flutter 1.x
    • Overview
    • Install
    • Track
    • Consent Management
    • Data Management
    • API Reference
    • Release Notes
  • Flutter 2.x
    • Overview
    • Install
    • Track
    • Consent Management
    • Data Management
    • API Reference
      • Tealium
      • TealiumConfig
      • VisitorProfile
    • Release Notes
  • iOS (Objective-C)
    • Overview
    • Install
    • Track
    • Data Layer
    • Data Management
    • Consent Management
    • Tag Management
    • Module List
      • Lifecycle Tracking Module
    • tvOS
    • watchOS
    • API Reference
    • Release Notes
  • iOS (Swift) 1.x
    • Overview
    • Install
    • Track
    • Data Layer
    • Data Management
    • App Extensions
    • Identity Resolution
    • Consent Management
    • Modules
    • Module List
      • AppData Module
      • Attribution Module
      • AutoTracking Module
      • Collect Module
      • Connectivity Module
      • CrashReporter Module
      • DataSource Module
      • DefaultStorage Module
      • Delegate Module
      • DeviceData Module
      • DispatchQueue Module
      • FileStorage Module
      • Lifecycle Module
      • Location Module
      • Logger Module
      • PersistentData Module
      • RemoteCommands Module
      • TagManagement Module
      • VisitorService Module
      • VolatileData Module
    • Feature Comparison
    • Working with Objective-C
    • API Reference
      • TealiumConfig
      • TealiumConsentCategories
      • TealiumConsentManagerDelegate
      • TealiumConsentManager
      • TealiumInstanceManager
      • TealiumPersistentData
      • TealiumVolatileData
      • Tealium
    • Release Notes
  • iOS (Swift) 2.x
    • Overview
    • Install
    • Track
    • Data Layer
    • Consent Management
    • App Extensions
    • Identity Resolution
    • Modules
    • Module List
      • AppData Module
      • AdobeVisitorService Module
      • Attribution Module
      • AutoTracking Module
      • Collect Module
      • Connectivity Module
      • CrashReporter Module
      • DeviceData Module
      • In-App Purchase Module
      • Lifecycle Module
      • Location Module
      • Media Module
      • RemoteCommands Module
      • TagManagement Module
      • VisitorService Module
    • Working with Objective-C
    • API Reference
      • LocationModule
      • MediaSession
      • Tealium
      • TealiumConfig
      • TealiumConsentCategories
      • TealiumConsentManager
      • TealiumDataLayer
      • TealiumInstanceManager
    • Release Notes
  • NativeScript
    • Overview
    • Install
    • Track
    • API Reference
      • Tealium
      • TealiumConfig
    • Release Notes
  • React Native 1.x
    • Overview
    • Install
    • Track
    • API Reference
    • Release Notes
  • React Native 2.x
    • Overview
    • Install
    • Track
    • Location Module
    • API Reference
    • Release Notes
  • Unity 1.x
    • Overview
    • Install
    • Track
    • API Reference
  • Unity 2.x
    • Overview
    • Install
    • Track
    • API Reference
  • Xamarin 1.x
    • Overview
    • Install
    • Track
    • Data Management
    • Consent Management
    • API Reference
    • Release Notes
  • Xamarin 2.x
    • Overview
    • Install
    • Track
    • Data Layer
    • Consent Management
    • API Reference
    • Release Notes
  • Web
  • Getting Started
    • Overview
    • Quick Start Guide
    • Web Concepts
    • Data Layer
      • An Introduction to the Data Layer
      • How the Data Layer Works for Websites
      • Data Layer Best Practices
      • Definitions
        • Retail
        • Publisher
        • Hotel
        • Travel
        • Basic Video Tracking
  • Adobe Launch
    • Overview
    • Install
    • Data Layer
  • AMP
    • Overview
    • Install
    • Track
    • Data Layer
  • Angular
    • Overview
    • Install
    • Track
    • API Reference
  • Google Tag Manager
    • Overview
    • Install
    • Data Layer
  • JavaScript (Web)
    • Overview
    • Install
    • Track
    • Data Layer
    • Universal Data Object (utag_data)
    • Universal Tag (utag.js)
    • Data Layer Object (b)
    • Single-Page Applications
    • Settings
    • Debugging
    • API Reference
      • Cookie Functions
      • GDPR Functions
      • Tracking Functions
      • Utility Functions
    • Release Notes
  • Server
  • C#
    • Overview
    • Install
    • Track
    • Data Layer
    • API Reference
    • Release Notes
  • HTTP API
    • Overview
    • Endpoint
    • Data Layer
  • Java
    • Overview
    • Install
    • Track
    • API Reference
    • Release Notes
  • Node
    • Overview
    • Install
    • Track
    • API Reference
  • Python
    • Overview
    • Install
    • Track
    • API Reference
  • Roku
    • Overview
    • Install
    • Track
    • API Reference
  • Ruby
    • Overview
    • Install
    • Track
    • API Reference
REMOTE COMMANDS

How It Works

Learn about the remote commands feature for mobile.

Remote commands are a client-side solution for triggering SDK functionality in your native app.

Use remote commands in two ways:

  • Vendor Integrations
    Vendor integrations are pre-built remote command modules that implement a vendor’s native API. See the list of remote command integrations.
  • Custom Commands
    Custom commands offers an open framework to define your own native custom commands and trigger them using the Custom Remote Command tag in Tealium iQ Tag Management.

Vendor Integrations

A vendor integration is a pre-built remote command module that installs the vendor SDK and defines native code handlers for the vendor’s API.

Implementing a vendor integration requires the following:

  • Vendor remote command module
    In your app build scripts, replace the vendor SDK with the Tealium remote command module. The remote command module handles the vendor SDK installation and setup for you.
  • Configuration (Choose one of the following)
    • JSON File
      A JSON file, loaded locally or hosted remotely, containing the vendor settings, data mappings, and event triggers.
    • Remote Command Tag
      A tag in iQ Tag Management that offers configuration options for the vendor’s API (for use with the Tag Management module).

See the list of remote command vendor integrations.

Remote commands are configured to specific vendor SDK releases to avoid any incompatibility between the Tealium Remote Command code and the vendor SDK. If you require updated vendor SDK functionality, contact Tealium support for help with upgrading.

The following diagram illustrates how vendor integrations and custom remote commands trigger functionality in your native app. Beginning with a visitor purchase tracked in your app, the Tealium SDK triggers remote commands in apps like Firebase, Facebook, or your own custom remote command. The remote command can trigger any native method available in the SDK, such as logging a purchase in Firebase, tracking an event in Facebook App Events, or displaying a custom notification in your app.

remote_command_data_flow_diagram.png

JSON File

Configure a vendor integration using a JSON file. Load this file locally in the app or from a remotely hosted URL. A JSON template file is available for each vendor integration.

Mappings

A JSON template file has three main sections: config, mappings, and commands.

  • config
    This section sets vendor SDK initialization options such as client ID, API key, or the log level. For example, the following sets the application ID:

    {
      "config": {
        "applicationid": "appid123"
      }
    }
    
  • mappings
    This section defines your data mappings. The following mapping assigns the data layer variable product_id to the vendor parameter param_item_id.

    {
      "mappings": {
        "product_id": "param_item_id"
      }
    }
    

    The vendor parameter may use a prefix with dot notation to scope a mapping to a specific object in the payload. The prefix defines the object and the value to the right of the . becomes a property of the object. For example, the following mapping assigns product_id to the param_item_id variable of the event object. The remote commands parser creates an event object with param_item_id as one of its properties.

    {
      "mappings": {
        "product_id": "event.param_item_id"
      }
    }
    

    The object prefix is typically event., product., or purchase., but may be any custom object name. Refer to the JSON template files to see the object prefixes used for your vendor integration.

  • commands
    This section maps Tealium event names to the vendor’s events. The value left of the : is the Tealium event name and the right value is the Tealium wrapper for the vendor’s method. In the following example, the Tealium event cart_add is mapped to the vendor method logevent:

    {
      "commands": {
        "cart_add": "logevent"
      }
    }
    

Example

The following is an example JSON configuration:

{
    "config": {
        "analytics_enabled": "true",
        "session_timeout_seconds": "30",
        "log_level": "max",
        "minimum_seconds": "100",
        ...
    },
    "mappings": {
        "event_title": "event_name",
        "product_brand": "event.param_item_brand",
        "product_category": "event.param_item_category",
        "product_id": "event.param_item_id",
        "product_list": "event.param_item_list",
        "product_location_id": "event.param_item_location_id",
        "product_name": "event.param_item_name",
        "product_variant": "event.param_item_variant",
        ...
    },
    "commands": {
        "launch": "config",
        "cart_add": "logevent",
        ...
    }
}

Load Options

There are two options for loading the JSON configuration file: as a local file or from a hosted URL.

    To use a local configuration file stored in your iOS (Swift) app:

    let config = TealiumConfig(account: "ACCOUNT",
            profile: "PROFILE",
            environment: "ENVIRONMENT")
    config.dispatchers = [Dispatchers.TagManagement, Dispatchers.RemoteCommands]
    config.remoteAPIEnabled = true
    
    tealium = Tealium(config: config) { _ in
        guard let remoteCommands = self.tealium?.remoteCommands else {
            return
        }
        let facebook = FacebookRemoteCommand(type: .local(file: "facebook"))
        remoteCommands.add(facebook)
    }
    

    Host the configuration file, accessible as a URL, using the hosted data layer.

    To use the hosted configuration file in your iOS (Swift) app:

    let config = TealiumConfig(account: "ACCOUNT",
            profile: "PROFILE",
            environment: "ENVIRONMENT")
    config.dispatchers = [Dispatchers.TagManagement, Dispatchers.RemoteCommands]
    config.remoteAPIEnabled = true
    
    tealium = Tealium(config: config) { _ in
        guard let remoteCommands = self.tealium?.remoteCommands else {
            return
        }
        let facebook = FacebookRemoteCommand(type: .remote(url: "https://tags.tiqcdn.com/dle/ACCOUNT/PROFILE/facebook.json"))
        remoteCommands.add(facebook)
    }
    

    To use a local configuration file stored in your Android (Kotlin) app:

    val config = TealiumConfig(application,
            "ACCOUNT", "PROFILE",
            Environment.DEV,
            dispatchers = mutableSetOf(Dispatchers.RemoteCommands));
    var tealium = Tealium.create(TEALIUM_MAIN, config) {
      val facebook = FacebookRemoteCommand(this);
      remoteCommands?.add(facebook, filename = "facebook.json");
    }
    

    Host the configuration file, accessible as a URL, using the hosted data layer.

    To use the hosted configuration file in your Android (Kotlin) app:

    val config = TealiumConfig(application,
            "ACCOUNT", "PROFILE",
            Environment.DEV,
            dispatchers = mutableSetOf(Dispatchers.RemoteCommands));
    var tealium = Tealium.create(TEALIUM_MAIN, config) {
      val facebook = FacebookRemoteCommand(this);
      remoteCommands?.add(facebook, remoteUrl = "https://tags.tiqcdn.com/dle/ACCOUNT/PROFILE/facebook.json");
    }
    

    Vendor Templates

    The following remote command JSON templates are available.

    • AppsFlyer
    • Braze
    • Contentsquare
    • Facebook
    • Firebase
    • Kochava
    • Usabilla

    Consent Management

    If the vendor SDK supports consent management, and the client wants to manage consent for the vendor SDK, then verify that the vendor SDK is configured to be opted-out by default. Use the Tealium iQ Remote Command tag for this vendor when the user opts-in, based on the consent status stored in the Tealium SDK.

    Custom Commands

    When using iQ Tag Management in your app, custom remote commands provide the ability to trigger native code blocks from the non-rendered webview. This is used in cases where data held inside the non-rendered webview needs to be passed back to the native code for further processing.

    Remote commands use custom URL schemes as a way for JavaScript tags to trigger methods in your app. A tag in the non-rendered webview sends the app requests which are processed by a remote command handler that triggers custom code or a vendor SDK.

    Components

    A remote command has a command name and a payload of data.

    • Command
      The name of the command, or command ID, registered with native code in your app.
    • Payload
      The data passed to the native app and received as an object named requestPayload in the response callback of the handler.

    Define remote commands in your native app at build time. The Custom Remote Command tag only executes pre-defined code on the device.

    Native Code

    In the native code, the add() function registers a remote command handler. The callback function response has access to the payload with response.payload. In the following example, the referenced payload variables have a matching data layer variable configured in iQ Tag Management.

      tealium = Tealium(config: config) { [weak self] _ in
          let remoteCommand = RemoteCommand(commandId: "myRemoteCommand", description: "") { response in
              guard let payload = response.payload,
              let myVariable = payload["myVariable"] as? String else {
                  return
              }
              print(myVariable)
          }
          self.tealium?.remoteCommands?.add(remoteCommand)
      }
      
      val remoteCommand = object : RemoteCommand("sample", "testing RCs") {
          override fun onInvoke(response: Response) {
              Logger.dev(BuildConfig.TAG, "ResponsePayload for webView RemoteCommand ${response.requestPayload}")
          }
      }
      val tealium = Tealium.create(instanceName, config) {
          remoteCommands?.add(webViewRemoteCommand)
      }
      

      Add a module for the vendor integration to the build script for your platform. Modules are named in the format of TealiumVendorXYZ, for example TealiumBraze.

      To install, replace the vendor’s dependency with the Tealium remote command dependency. For example, remove the following line:

      pod "VendorXYZ-iOS-SDK"
      

      Then add the following line:

      pod "TealiumVendorXYZ"
      

      Use Case: Purchase Survey

      The following steps demonstrate how to use a remote command to trigger a survey in your app after a user completes a purchase.

      1. Create native code that prompts the user to take a survey, passing the message and URL as method parameters (from the non-rendered webview).
      2. Register the block of code as a remote command with the Tealium API.
      3. Add the Custom Remote Command tag in iQ Tag Management and set the command ID to the same command registered in the native code.
      4. Set data mappings to pass specific variables back to the app, such as survey_title or survey_url.
      5. In the native code, use the variables passed back in the response payload to display the survey to the user.

      After completing these steps, you are able to configure the survey title, URL, and logic using extensions in iQ Tag Management without re-deploying your app.

      Remote Command Tag

      Use iQ Tag Management where a remote command is set up as an instance of the custom Remote Command tag with the following settings:

      • Command ID
        The name of the command (the same name used in the native method addRemoteCommandID).
      • Load rule
        A rule to determine when to trigger the remote command.
      • Mapped variables
        The data to include in the remote command. Mapped data layer variables are available in the response.requestPayload object in the native code callback.

      Example Remote Command Tag

      The following is an example of a tracked event in Swift.

      tealium?.track(
          title: "My Screen",
          data: ["tealium_event": "my_event", "my_variable": "my_value"]
      );
      

      The tag setup is defined as follows:

      • Command ID
        myRemoteCommand
      • Load rule
        IF tealium_event EQUALS my_event
      • Mapped variable
        my_variable -> myVariable

      The following screenshots show the example configured in iQ Tag Management.

      tag-example.png


       

      Was this article helpful?

      This page was last updated: May 13, 2022      

      Thank you for your feedback!

      Table of Contents

      • Vendor Integrations
      • JSON File
        • Mappings
        • Example
        • Load Options
        • Vendor Templates
      • Consent Management
      • Custom Commands
        • Components
        • Native Code
        • Use Case: Purchase Survey
      • Remote Command Tag
        • Example Remote Command Tag
      • Platforms
      • Partners
      • Forums
      • Mobile
      • Getting Started
      • Remote Commands
      • Android (Java)
      • Android (Kotlin)
      • Cordova 1.x
      • Cordova 2.x
      • Flutter 1.x
      • Flutter 2.x
      • iOS (Objective-C)
      • iOS (Swift) 1.x
      • iOS (Swift) 2.x
      • NativeScript
      • React Native 1.x
      • React Native 2.x
      • Unity 1.x
      • Unity 2.x
      • Xamarin 1.x
      • Xamarin 2.x
      • Web
      • Getting Started
      • Adobe Launch
      • AMP
      • Angular
      • Google Tag Manager
      • JavaScript (Web)
      • Server
      • C#
      • HTTP API
      • Java
      • Node
      • Python
      • Roku
      • Ruby