Remote Commands (TagBridge)

Remote Commands (TagBridge)

by on ‎03-22-2018 08:48 AM (405 Views)

The Remote Command system allows you to control certain aspects of your app remotely using Tealium IQ. Starting in version 1.1.0 of the Cordova plugin, it's possible to register a JavaScript callback function with the Tealium plugin, which can then be called remotely from Tealium iQ whenever a specific set of load rules is satisfied.

For example, you might wish to trigger a modal overlay in your Cordova app, which invites the user to participate in a survey when the user performs a specific function (completes a purchase, subscribes to emails etc.). The advantage of controlling this in Tealium iQ is that the text displayed in the modal overlay can be configured remotely, and additionally the overlay can be completely enabled/disabled via Tealium iQ without the need for an app release. You could also use Tealium iQ to hold config information for other 3rd party SDKs/plugins (e.g. API keys), which would give you the ability to quickly and dynamically change this information based on some information passed into Tealium iQ by a trackEvent or trackView call. For example, you could dynamically change API keys based on the Tealium environment currently loaded in the app (dev = XXXXXX, prod = YYYYYY).

RemoteCommand Code Example

// this code would normally be implemented in the main .js file for your app
function tealiumInit(accountName, profileName, environmentName, instanceName){
        tealium.init({
                 account : accountName       // REQUIRED: Your account.
                 , profile : profileName              // REQUIRED: Profile you wish to use.
                 , environment : environmentName         // REQUIRED: "dev", "qa", or "prod".
                 , instance : instanceName || window.tealium_instance // instance name used to refer to the current tealium instance
                 , isLifecycleEnabled: "true" // explicitly enabling lifecycle tracking. Note string value required, not boolean
                 // , collectDispatchURL:"https://collect.tealiumiq.com/vdata/i.gif?tealium_account=services-crouse&tealium_profile=mobile"
                 , collectDispatchProfile:"demo"
                 });
}

function onDeviceReady() {
    // call our custom tealiumInit function
    tealiumInit("tealiummobile", "demo", "dev", "tealium_main");
    console.log("onDeviceReady");
    tealium.addRemoteCommand("getTIQMessage", window.tealium_instance, function (message){
		 // message is a JSON object containing mapped key-value pairs from TiQ
        if (message && message.message_text) {
            alert(message.message_text);
        }
    });
    tealium.addRemoteCommand("getAnotherMessage", window.tealium_instance, function (message){
        // message is a JSON object containing mapped key-value pairs from TiQ
        if (message && message.message_text) {
            alert(message.message_text);
        }    
     });
    // simple example to change the background color of the view to a color code returned from TiQ
    tealium.addRemoteCommand("changeBackgroundColor", window.tealium_instance, function (message){
        // message is a JSON object containing mapped key-value pairs from TiQ
        if (message && message.bg_colorcode) {
            document.body.style.background = message.bg_colorcode;
        }    
     });     
}

This example is also demonstrated in the TealiumSample app included on GitHub.

Remote Commands Tealium iQ Config

Prerequisite: Ensure you are using utag.js loader version 4.40 or above, or you may encounter issues with commands double-firing.

  1. Add the "TagBridge Custom Command" tag in Tealium iQ, and in the "Command ID" box on the tag config screen, enter the name of the command you wish to call, e.g. changeBackgroundColor
  2. Add any load rules you wish to associate with this command, e.g. "screen_title contains confirmation screen"
  3. Create a new variable in Tealium iQ called "app_background_color" or similar
  4. Add a new mapping from "app_background_color" to a destination of "bg_colorcode" in the "TagBridge Custom Command" tag
  5. In an extension, set the value of "app_background_color" to the desired Hex color code (e.g. #FFFF00 for yellow, hash/pound sign included).
  6. Once you have published your profile, and when your load rules are satisfied, the app background color will change to yellow.

Idea: you could use a combination of setTimeout and cookies in a Tealium iQ JavaScript extension to fire your Remote Command after a delay, or only once within a given time period (e.g. 30 days).