How It Works

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.

You can 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. (See List of Remote Commands Interations)
• Custom Commands - your own custom commands defined in native code and configured in iQ Tag Management with the TagBridge Custom Command tag.

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 reponse callback of the handler.

Remote commands must be defined in your native app at build time. The remote command tag can only execute 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 can access the payload within response.requestPayload. Payload variables referenced here will 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
        }
    }
)

TagBridge Custom Command Tag

In iQ Tag Management, a remote command is set up as an instance of the TagBridge Custom Command tag with the following settings:

• Command ID: set to the name of the command (same name used in native code method addRemoteCommandID).
• Load Rule: a rule to determine when the remote command should be triggered.
• Mapped Variables: mapped data layer variables will be available in the response.requstPayload object in the native code callback.

Here is how an event goes from being tracked in your app to triggering a remote command.

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 pre-built remote command for a vendor takes care of the native code requirements for you. The remote command module installs the vendor SDK and defines remote command handlers for the vendor’s SDK methods.

Implementing a remote command integration requires the following:

• Vendor Remote Command Module
  Replace the vendor’s SDK install with the remote command module in your app build scripts. 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. Supported vendor SDK methods and data variables are configured as tag settings or data mappings.

Native Code

A module for the vendor integration can be added 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.