How It Works

Remote commands combine the power of native app code with the convenience and control of tags in Tealium 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. See the list of remote command 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 provide the ability to trigger native code blocks from the non-rendered web view when using Tag Management in your app. This is 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 non-rendered web view or want to personalize parts of your app, such as launching a survey after the user has made a purchase.

The steps to configure a post-purchase survey would be:

1. Create native code capable of prompting the user to take a survey where the message and URL to the survey are passed as method parameters (these will come from the non-rendered web view).
2. Register this block of code as a remote command with the Tealium API.
3. In iQ Tag Management, add the Custom Remote Command tag 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 those variables passed back in the response payload to display the survey to the user.

You can now control the survey title, URL, and logic using extensions in iQ Tag Management without needing to re-deploy your app.

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 and with a tag in iQ Tag Management.
• Payload
  The data passed from the tag to the native app, configured as data mappings in iQ Tag Management, 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.