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 > Add Package Dependencies.
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 and Libraries

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

Configure the Remote Command tag in Tag Management. You can also use a JSON file in your app or on a remote server. After configuration, register the remote command by using addRemoteCommand() on TealiumConfig. Complete registration before you initialize Tealium:

var tealium: Tealium?

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

let remoteCommand = RemoteCommand(commandId: "display", description: "Display Prompt") { response in
    guard let payload = response.payload else {
        return
    }
    print("Use response payload: \(payload)")
}
config.addRemoteCommand(remoteCommand)

tealium = Tealium(config: config)

var tealium: Tealium?

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

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)")
}
config.addRemoteCommand(remoteCommand)

tealium = Tealium(config: config)

var tealium: Tealium?

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

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)")
}
config.addRemoteCommand(remoteCommand)

tealium = Tealium(config: config)

Add a remote command after initialization

Add remote commands after you initialize Tealium by using the tealium.remoteCommands manager. When possible, add remote commands in TealiumConfig to ensure they receive all events. By default, webview commands initialize on load, so adding them later via tealium.remoteCommands may cause them to miss initialization.

If you need to add a remote command after Tealium is initialized, use this pattern:

tealium = Tealium(config: config)

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)")
}
tealium?.remoteCommands.add(remoteCommand)

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 Tag Management 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);
}