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.

Requirements

Implementing a vendor integration requires the following:

  • Vendor remote command module
    In your app build scripts, replace the vendor SDK with the Tealium remote command module. The remote command module handles the vendor SDK installation and setup for you.
  • Configuration (Choose one of the following) * 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.

Remote commands are configured to specific vendor SDK releases to avoid any incompatibility between the Tealium Remote Command code and the vendor SDK. If you require updated vendor SDK functionality, contact Tealium support for help with upgrading.

How it works

The following diagram illustrates how vendor integrations and custom remote commands trigger functionality in your native app. Beginning with a visitor purchase tracked in your app, the Tealium SDK triggers remote commands in apps like Firebase, Facebook, or your own custom remote command. The remote command can trigger any native method available in the SDK, such as logging a purchase in Firebase, tracking an event in Facebook App Events, or displaying a custom notification in your app.

Remote command data flow diagram

JSON File

Configure a vendor integration using a JSON file. Load this file locally in the app or from a remotely hosted URL. A JSON template file is available for each vendor integration.

A JSON template file has three sections: config, mappings, and commands.

Configuration Mapping

The config section sets vendor SDK initialization options such as client ID, API key, or the log level. For example, the following sets the application ID:

{
    "config": {
        "applicationid": "appid123"
    }
}

Data Mapping

The mappings section defines your data mappings. The following mapping assigns the data layer variable product_id to the vendor parameter param_item_id.

{
    "mappings": {
        "product_id": "param_item_id"
    }
}

The vendor parameter may use a prefix with dot notation to scope a mapping to a specific object in the payload. The prefix defines the object and the value to the right of the . becomes a property of the object. For example, the following mapping assigns product_id to the param_item_id variable of the event object. The remote commands parser creates an event object with param_item_id as one of its properties.

{
    "mappings": {
        "product_id": "event.param_item_id"
    }
}

The object prefix is typically event., product., or purchase., but may be any custom object name. Refer to the JSON template files to see the object prefixes used for your vendor integration.

Commands

The commands section maps Tealium event names to the vendor’s events. The value left of the : is the Tealium event name and the right value is the Tealium wrapper for the vendor’s method. In the following example, the Tealium event cart_add is mapped to the vendor method logevent:

{
    "commands": {
        "cart_add": "logevent"
    }
}

Example

The following is an example JSON configuration:

{
    "config": {
        "analytics_enabled": "true",
        "session_timeout_seconds": "30",
        "log_level": "max",
        "minimum_seconds": "100",
        ...
    },
    "mappings": {
        "event_title": "event_name",
        "product_brand": "event.param_item_brand",
        "product_category": "event.param_item_category",
        "product_id": "event.param_item_id",
        "product_list": "event.param_item_list",
        "product_location_id": "event.param_item_location_id",
        "product_name": "event.param_item_name",
        "product_variant": "event.param_item_variant",
        ...
    },
    "commands": {
        "launch": "config",
        "cart_add": "logevent",
        ...
    }
}

Load Options

There are two options for loading the JSON configuration file: as a local file or from a hosted URL.

To use a local configuration file stored in your iOS (Swift) app:

let config = TealiumConfig(account: "ACCOUNT",
        profile: "PROFILE",
        environment: "ENVIRONMENT")
config.dispatchers = [Dispatchers.TagManagement, Dispatchers.RemoteCommands]
config.remoteAPIEnabled = true

tealium = Tealium(config: config) { _ in
    guard let remoteCommands = self.tealium?.remoteCommands else {
        return
    }
  	let facebook = FacebookRemoteCommand(type: .local(file: "facebook"))
	remoteCommands.add(facebook)
}

Host the configuration file, accessible as a URL, using the hosted data layer.

To use the hosted configuration file in your iOS (Swift) app:

let config = TealiumConfig(account: "ACCOUNT",
        profile: "PROFILE",
        environment: "ENVIRONMENT")
config.dispatchers = [Dispatchers.TagManagement, Dispatchers.RemoteCommands]
config.remoteAPIEnabled = true

tealium = Tealium(config: config) { _ in
    guard let remoteCommands = self.tealium?.remoteCommands else {
        return
    }
  	let facebook = FacebookRemoteCommand(type: .remote(url: "https://tags.tiqcdn.com/dle/ACCOUNT/PROFILE/facebook.json"))
	remoteCommands.add(facebook)
}

To use a local configuration file stored in your Android (Kotlin) app:

val config = TealiumConfig(application,
        "ACCOUNT", "PROFILE",
        Environment.DEV,
        dispatchers = mutableSetOf(Dispatchers.RemoteCommands));
var tealium = Tealium.create(TEALIUM_MAIN, config) {
  val facebook = FacebookRemoteCommand(this);
  remoteCommands?.add(facebook, filename = "facebook.json");
}

Host the configuration file, accessible as a URL, using the hosted data layer.

To use the hosted configuration file in your Android (Kotlin) app:

val config = TealiumConfig(application,
        "ACCOUNT", "PROFILE",
        Environment.DEV,
        dispatchers = mutableSetOf(Dispatchers.RemoteCommands));
var tealium = Tealium.create(TEALIUM_MAIN, config) {
  val facebook = FacebookRemoteCommand(this);
  remoteCommands?.add(facebook, remoteUrl = "https://tags.tiqcdn.com/dle/ACCOUNT/PROFILE/facebook.json");
}

Vendor Templates

The following remote command JSON templates are available.

Was this page helpful?

This page was last updated: January 7, 2023