RemoteCommands Module

Learn more about remote commands.

Requirements

• If using the webview remote command, the TagManagement module is required.

Not a compile-time dependency, but remote commands are triggered from the module.

Supported Platforms

• iOS
• macOS (JSON only)
• tvOS (JSON only)
• watchOS (JSON only)

Install

Install the RemoteCommands module with Swift Package Manager, CocoaPods or Carthage.

Swift Package Manager (Recommended)

Supported in version 1.9.0+, the Swift Package Manager (SMP) is the recommended and simplest way to install the Tealium Swift library:

1. In your Xcode project, select File > Swift Packages > Add Package Dependency
2. Enter the repository URL: https://github.com/tealium/tealium-swift
3. Configure the version rules. Typically, "Up to next major" is recommended. If the current Tealium Swift library version does not appears in the list, then reset your Swift package cache.
4. Select the RemoteCommands module from the list of modules to install and add it each of your app targets in your Xcode project, under Frameworks > Libraries & Embedded Content

Learn more about the SPM installation for iOS.

CocoaPods

To install the RemoteCommands module with CocoaPods, add the following pod to your Podfile:

pod 'tealium-swift/RemoteCommands'

Learn more about the CocoaPods installation for iOS.

Carthage

To install the RemoteCommands module with Carthage, following these steps:

1. Go to the app target’s General configuration page in Xcode.

2. Add the following framework to the Embedded Binaries section:

   TealiumRemoteCommands.framework
   

3. If you need to interact with the RemoteCommands API, add the following required import statement to your project:

   import TealiumRemoteCommands
   

Learn more about the Carthage installation for iOS.

Remote Command Options

There are two configuration options for remote commands:

• 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.

Examples

The Remote Command tag is configurable in Tealium iQ Tag Management, via a JSON file in your app, or JSON file on a remote server. Once the remote command is configured and the module is installed in your app, add the following lines to the initialization:

var tealium: Tealium?

let config = TealiumConfig(account: "ACCOUNT",
                     		profile: "PROFILE",
                     		environment: "ENVIRONMENT",
                    		dataSource: "DATASOURCE")

tealium = Tealium(config: config) { [weak self] _ in
    guard let remoteCommands = self?.tealium?.remoteCommands else {
        return
    }
    let remoteCommand = RemoteCommand(commandId: "display", description: "Display Prompt") { response in
        guard let payload = response.payload else {
            return
        }
        print("Use response payload: \(payload)")
    }
    remoteCommands.add(remoteCommand)
}

var tealium: Tealium?

let config = TealiumConfig(account: "ACCOUNT",
                     		profile: "PROFILE",
                     		environment: "ENVIRONMENT",
                    		dataSource: "DATASOURCE")

tealium = Tealium(config: config) { [weak self] _ in
    guard let remoteCommands = self?.tealium?.remoteCommands else {
        return
    }
    let remoteCommand = RemoteCommand(commandId: "display", description: "Display Prompt", type: .local(file: "FILENAME")) { response in
        guard let payload = response.payload else {
            return
        }
        print("Use response payload: \(payload)")
    }
    remoteCommands.add(remoteCommand)
}

var tealium: Tealium?

let config = TealiumConfig(account: "ACCOUNT",
                     		profile: "PROFILE",
                     		environment: "ENVIRONMENT",
                    		dataSource: "DATASOURCE")

tealium = Tealium(config: config) { [weak self] response in
    guard let remoteCommands = self?.tealium?.remoteCommands else {
        return
    }
    let remoteCommand = RemoteCommand(commandId: "display", description: "Display Prompt", type: .remote(url: "https://tags.tiqcdn.com/dle/ACCOUNT/PROFILE/FILENAME.json")) { response in
        guard let payload = response.payload else {
            return
        }
        print("Use response payload: \(payload)")
    }
    remoteCommands.add(remoteCommand)
}

After the JSON file has been configured and either added to your app or hosted on a server, learn about the different JSON load options.

Data Layer

No additional variables are introduced by this module.

API Reference

init()

Creates a new remote command object ready to be passed to the add command.

The following is a usage example:

let customCommand = TealiumRemoteCommand(commandId: "logger",
                                        description: "Log Response object to console",
                                        type: .local(file: "logger"))
                                        { (response) in
                                            // code to execute
                                            print("Custom command response: \(response)")
                                        })

add()

As of 1.6.5, we recommend adding Remote Commands using the TealiumConfig addRemoteCommand() method

Registers a specified remote command with Tealium for later triggering. Tealium must have been initialized before adding a new Remote Command.

add(_ remoteCommand: TealiumRemoteCommandProtocol)

The following is a usage example:

var tealium: Tealium?
let customCommand = RemoteCommand(commandId: "logger",
    description: nil)
    { response in
        // code to execute
        print("Custom command response: \(response)")
    }
if let remoteCommands = self.tealium?.remoteCommands {
        remoteCommands.add(customCommand)
} else {
		print("Remote commands not available")
}

remove()

Removes a previously-registered remote command to prevent it being triggered again.

remove(commandWithId: String)

remove(jsonCommand: String)

// assumes "tealium" previously instantiated
tealium?.remoteCommands?.remove(commandWithId: "logger")

tealium?.remoteCommands?.remove(jsonCommand: "logger")

remoteHTTPCommandDisabled

When true, disables the built-in remote HTTP command, but leaves the remote commands module enabled for other commands. Default is false - or Remote HTTP Command enabled

remoteHTTPCommandDisabled

The following is a usage example:

// assumes "config" previously instantiated (`TealiumConfig()`)
config.remoteHTTPCommandDisabled = false

Remote HTTP Command

This is a reserved internal command with identifier _http which triggers an HTTP request from native code, and passes the response back to the Tealium iQ web view. This is used in some cases to bypass CORS restrictions that may be encountered in a web browser. To use this command, there are specific mapping names you must use:

The following is an example callback function:

var my_callback = function(code, body) {
   // assuming the response body was a JSON object, this logs a variable called my_response_variable to the console in the web view
	console.log(body.my_response_variable);
}