How It Works | Remote Commands |Tealium Developer Docs

Remote commands combine the power of native app code with the convenience and control of tags in iQ Tag Management. Remote commands use custom URL schemes as a way for JavaScript tags to trigger methods inside your app. A tag in the non-rendered web view sends custom requests for the app to receive. These requests are processed by a remote command handler that triggers custom native code or a vendor’s SDK.

Use remote commands in two ways:

Vendor Integrations - Solutions pre-built for a vendor SDK using a native remote command module that implements the vendor API and a matching vendor tag in iQ Tag Management. Learn more about Remote Commands Integrations.
Custom Commands - Your own custom commands defined in native code and configured in iQ Tag Management with the Custom Remote Command tag.

Introduction

Remote Commands (also known as Custom Remote Command/Dynamic Triggers) provide the ability to trigger native code blocks from within the Tealium iQ non-rendered web view. For this reason, Remote Commands are available if you have implemented or explicitly enabled the Tag Management feature/module in your app, since Tealium iQ cannot execute arbitrary code on the device.

This feature is primarily used for cases where data held inside the non-rendered web view needs to be passed back to the native code for further processing. For example, you may need to access a value stored in a cookie or localStorage inside the Tealium iQ web view. Another use for this feature would be to personalize parts of your app, for example, you may wish to trigger a survey in the app once the user has been through a particular journey, such as making a purchase.

The flow for this particular example would be:

Create some generic native code capable of triggering a local notification on the device, which prompts the user to take a survey.
Register this block of code as a Remote Command with the Tealium API.
In Tealium iQ, create a new “Custom Remote Command” tag, and make sure the command ID matches the command ID you used to register the command in the native code.
Mappings can be set up to pass specific data variables back to the app. For example, you might wish to pass a customized survey message back to the app such as “Thank you for making a purchase. Would you mind taking a short survey?”. You might also pass back a specific URL to open when the user clicks the notification, so that you can pass the user through to a specific web-hosted survey using your survey tool of choice.
In the app, the native code will look for specific variables passed back in the response such as survey_url and survey_title, display the message in the notification, and launch a web view or the native browser when the user clicks the notification.
If you wish to change the survey URL, or the message displayed to the user, you can now control this through Tealium iQ extensions, without needing to re-deploy your app. You can also disable the survey at-will, or change the trigger that leads to the survey being displayed. For example, display on the home screen instead of the order confirmation screen.

Components

A remote command is structured similarly to a tracked event: it 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 and with a tag in Tealium iQ.
payload: the data passed from the tag to the native app, configured as data mappings and received in the app as a requestPayload object in the response callback of the handler.

Remote commands must be defined in your native app at build time. The remote command tag only executes code that is already defined on the device.

Native Code

In the native code, a helper function named addRemoteCommandID registers a handler for a remote command. The callback function responseBlock accesses the payload within response.requestPayload. Payload variables referenced here have a matching data layer variable configured in iQ Tag Management.

TealiumHelper.shared.tealium.addRemoteCommandID(
    "myRemoteCommand",
    description: "",
    targetQueue: DispatchQueue.main,
    responseBlock: { response in
        guard let myVariable = response.requestPayload["myVariable"] as? String else {
            return
        }
    }
)

Custom Remote Command Tag

In iQ Tag Management, 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.requstPayload object in the native code callback.

Example remote command tag:

Tracked Event:

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

Tag Setup:

Command ID
myRemoteCommand
Load Rule
IF tealium_event EQUALS my_event
Mapped Variable
my_variable -> myVariable

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 remote command integration requires the following:

Vendor Remote Command Module
In your app build scripts, Replace the vendor SDK with the remote command module. The remote command module handles the vendor SDK installation and setup for you.
Vendor Remote Command Tag
In iQ Tag Management, add the remote command tag for the vendor integration. Configure the tag settings and data mappings to implement the desired vendor methods.

Native Code

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 this line
pod "VendorXYZ-iOS-SDK"

// Add this line
pod "TealiumVendorXYZ"

Remote Command Tag

A remote command tag for the vendor integration is offered in iQ Tag Management. Use this tag just like a regular website tag. Each remote command tag offers event mappings for the vendor’s SDK methods, which are defined as remote commands in the app module.

List of remote command vendor integrations.