• Platforms
  • Partners
  • Forums
  • TLC Tealium Learning Center Tealium Learning
    Community
  • Discussions & Ideas Dicussions & Ideas
  • Product Guides Product Guides
  • Knowledge Base Knowledge Base
  • Developer Docs Developer Docs
  • Education Education
  • TLC Blog TLC Blog
  • Support Desk Support Desk
  • CDH Customer Data Hub Customer Data Hub

Table of Contents

  • Requirements
  • How It Works
  • Install
    • Dependency Manager
    • Manual (iOS)
  • Initialize
    • Android (Kotlin)
    • Android (Java)
    • iOS (Swift)
  • JSON Template
  • Track
  • Supported Methods
    • SDK Setup
    • Targeting Options
    • Set Custom Variables
    • Forms
REMOTE COMMANDS/INTEGRATIONS

Remote Command: Usabilla

Tealium remote command integration for Usabilla on Android and Swift/iOS.

Requirements

  • Usabilla app ID and form ID
  • One of these mobile libraries:
    • Tealium for Android-Kotlin (1.0.0+)
    • Tealium for Android-Java (5.9.0+ for Usabilla 1.0.0+ or <5.9.0 for previous versions)
    • Tealium for iOS-Swift
  • One of these remote command integrations:
    • Usabilla Remote Command JSON File (Requires Android-Kotlin 1.0.0+ or iOS-Swift 2.1.0+)
    • Usabilla Remote Command tag in Tealium iQ Tag Management

How It Works

The Usabilla integration uses three items:

  1. The Usabilla native SDK
  2. The remote commands module that wraps the Usabilla methods
  3. Either the JSON configuration file or Remote Command tag that translates event tracking into native Usabilla calls

Adding the Usabilla remote command module to your app automatically installs and builds the required Usabilla libraries. If you are using a dependency manager installation, there is no need to install the Usabilla SDK separately.

There are two remote command options: A JSON configuration file, or using iQ Tag Management to configure the mappings. A JSON configuration file is the recommended option for your vendor integration, hosted either remotely or locally within your app. If using iQ Tag Management, add the Remote Command tag for the vendor integration. Learn more about vendor integrations.

Install

Dependency Manager

We recommend using one of the following dependency managers for installation:

If you are using the Tealium iOS (Objective-C) library, use the manual installation method. The CocoaPods and Carthage options are only available if you are using the Tealium iOS (Swift) library.

    To install Usabilla remote commands for iOS using CocoaPods:

    1. Remove tealium-swift and pod "Usabilla" if they already exist your Podfile. The dependency for tealium-swift is already included in the TealiumUsabilla framework.

    2. Add the following dependency to your Podfile:

      pod "TealiumUsabilla"

      The TealiumUsabilla pod includes the following TealiumSwift dependencies:

      'tealium-swift/Core'
      'tealium-swift/TealiumDelegate'
      'tealium-swift/TealiumRemoteCommands'
      'tealium-swift/TealiumTagManagement'
    3. Import the modules TealiumSwift and TealiumUsabilla in your TealiumHelper file, and any other files that access the Tealium class or the Usabilla remote command.

    To install Usabilla remote commands for iOS using Carthage:

    1. Remove tealium-swift from your Cartfile. The dependency for tealium-swift is already included in the TealiumUsabilla framework.

    2. Remove the following line if it exists in your Cartfile:

      github "usabilla/usabilla-u4a-ios-swift-sdk"
    3. Add the following dependency to your Cartfile:

      github "tealium/tealium-ios-usabilla-remote-command"

    Tealium for Swift SDK (version 1.6.5+) requires the TealiumDelegate module to be included with your installation.

    To install Usabilla remote commands for Android using Maven:

    1. Install Tealium for Android (Kotlin) or Tealium for Android (Java), if you haven’t done so already.

    2. Import the Tealium-Usabilla remote commands by adding the following dependency in your app project’s build.gradle file:

      dependencies {
        implementation 'com.tealium.remotecommands:usabilla:1.0.0'
      }

    Manual (iOS)

    The manual installation for Usabilla remote commands requires the Tealium for Swift library to be installed. To install the Usabilla remote commands for your iOS project:

    1. Install the Usabilla SDK, if you haven’t already done so.

    2. Clone the Tealium iOS Usabilla remote command repo and drag the files within the Sources folder into your project.

    3. Add Dispatchers.RemoteCommands as a dispatcher

    4. Set the remoteAPIEnabled configuration flag to true

    Initialize

    For all Tealium libraries, you need to register the Usabilla remote command when you initialize.

    Android (Kotlin)

    Initialize remote commands with a JSON configuration file or the Remote Command tag for Tealium’s Android (Kotlin) library.

      The following code is designed for use with the JSON Remote Commands feature, using the local file option:

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

      Additional (optional) initialization parameters are available for the Usabilla SDK:

      • usabillaHttpClient = null
        Overrides the HttpClient object, which gives the possibility to inject a custom client to handle all the connections performed by the SDK. Learn more about the custom HTTP client.
      • usabillaReadyCallback = null
        Overrides the UsabillaReadyCallback object, which is a callback used to communicate when the initialization process ends.
      • autoFragmentManager = false
        Disables passive feedback (enabled by default). Passive feedback requires Android’s FragmentManager to be kept up-to-date and monitored using android.app.Application.ActivityLifecycleCallbacks.
      • autoFeedbackHandler = false
        Disables handling of event tracking for passive and campaign feedback forms as well as auto-removing forms that have been submitted or dismissed (enabled by default). Two android.content.BroadcastReceivers are registered to listen for Usabilla events that handle both passive and campaign feedback form closures.

      The following example shows usage of the optional parameters:

      val usabilla = UsabillaRemoteCommand(TEALIUM_MAIN, config,
              usabillaHttpClient = null,
              usabillaReadyCallback = null,
              autoFragmentManager = false,
              autoFeedbackHandler = false);

      The following code is designed for use with the Remote Command tag feature:

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

      Additional (optional) initialization parameters are available for the Usabilla SDK:

      • usabillaHttpClient = null
        Overrides the HttpClient object, which gives the possibility to inject a custom client to handle all the connections performed by the SDK. Learn more about the custom HTTP client.
      • usabillaReadyCallback = null
        Overrides the UsabillaReadyCallback object, which is a callback used to communicate when the initialization process ends.
      • autoFragmentManager = false
        Disables passive feedback (enabled by default). Passive feedback requires Android’s FragmentManager to be kept up-to-date and monitored using android.app.Application.ActivityLifecycleCallbacks.
      • autoFeedbackHandler = false
        Disables handling of event tracking for passive and campaign feedback forms as well as auto-removing forms that have been submitted or dismissed (enabled by default). Two android.content.BroadcastReceivers are registered to listen for Usabilla events that handle both passive and campaign feedback form closures.

      The following example shows usage of the optional parameters:

      val usabilla = UsabillaRemoteCommand(TEALIUM_MAIN, config,
              usabillaHttpClient = null,
              usabillaReadyCallback = null,
              autoFragmentManager = false,
              autoFeedbackHandler = false);

      Android (Java)

      Initialize remote commands with a JSON configuration file or the Remote Command tag for Tealium’s Android (Java) library.

        The JSON Remote Command file feature for Android is only available in the Kotlin SDK.

        The following code is designed for use with the Remote Command tag feature:

        Tealium.Config config = Tealium.Config.create(application, "ACCOUNT", "PROFILE", "ENVIRONMENT");
        Tealium teal = Tealium.createInstance(TEALIUM_MAIN, config);
        
        RemoteCommand usabilla = new UsabillaRemoteCommand(TEALIUM_MAIN, config);
        teal.addRemoteCommand(usabilla);

        Additional (optional) initialization parameters are available for the Usabilla SDK:

        • usabillaHttpClient = null
          Overrides the HttpClient object, which gives the possibility to inject a custom client to handle all the connections performed by the SDK. Learn more about the custom HTTP client.
        • usabillaReadyCallback = null
          Overrides the UsabillaReadyCallback object, which is a callback used to communicate when the initialization process ends.
        • autoFragmentManager = false
          Disables passive feedback (enabled by default). Passive feedback requires Android’s FragmentManager to be kept up-to-date and monitored using android.app.Application.ActivityLifecycleCallbacks.
        • autoFeedbackHandler = false
          Disables handling of event tracking for passive and campaign feedback forms as well as auto-removing forms that have been submitted or dismissed (enabled by default). Two android.content.BroadcastReceivers are registered to listen for Usabilla events that handle both passive and campaign feedback form closures.

        The following example shows usage of the optional parameters:

        RemoteCommand usabilla = new UsabillaRemoteCommand(TEALIUM_MAIN, config,
                usabillaHttpClient = null,
                usabillaReadyCallback = null,
                autoFragmentManager = false,
                autoFeedbackHandler = false);

        iOS (Swift)

        Initialize remote commands with a JSON configuration file or the Remote Command tag for Tealium’s Android (Java) library.

          The following code is designed for use with the JSON Remote Commands feature, using the local file option:

          var tealium : Tealium?
          let config = TealiumConfig(account: "ACCOUNT",
                                     profile: "PROFILE",
                                     environment: "ENVIRONMENT",
                                     dataSource: "DATASOURCE")
          config.dispatchers = [Dispatchers.TagManagement, Dispatchers.RemoteCommands]
          config.remoteAPIEnabled = true // Required to use Remote Commands
          
          tealium = Tealium(config: config) { _ in
              guard let remoteCommands = self.tealium?.remoteCommands else {
                  return
              }
              let usabilla = UsabillaRemoteCommand(type: .local(file: "usabilla"))
              remoteCommands.add(usabilla)
          }

          The following code is designed for use with the Remote Command tag feature:

          var tealium : Tealium?
          let config = TealiumConfig(account: "ACCOUNT",
                                     profile: "PROFILE",
                                     environment: "ENVIRONMENT",˜˜
                                     dataSource: "DATASOURCE")
          config.dispatchers = [Dispatchers.TagManagement, Dispatchers.RemoteCommands]
          config.remoteAPIEnabled = true // Required to use Remote Commands
          
          tealium = Tealium(config: config) { _ in
              guard let remoteCommands = self.tealium?.remoteCommands else {
                  return
              }
              let usabilla = UsabillaRemoteCommand()
              remoteCommands.add(usabilla)
          }

          JSON Template

          If you are configuring remote commands using a JSON configuration file, refer to the following template to get started. The template includes common mappings used in a standard e-commerce installation. Edit the mappings as needed.

          {
            "config": {
              "appId": "YOUR_APP_ID",
              "debugEnabled": true
            },
            "mappings": {
                "event_name": "event",
                "display_campaigns": "canDisplayCampaigns",
                "dismiss_automatically": "dismissAutomatically",
                "form_id": "formId",
                "form_ids": "formIds",
                "customer_first_name": "custom.customer_first_name"
          },
            "commands": {
              "launch": "initialize",
              "display_campaigns": "candisplaycampaigns",
              "dismiss": "dismissautomatically",
              "button_click": "sendevent",
              "load_form": "loadfeedbackform",
              "set_variables": "setcustomvariable",
              "reset": "resetcampaigndata"
            }
          }

          Track

          Events are tracked automatically for successful and unsuccessful form loads, as well as both passive and campaign feedback forms.

          Supported Methods

          Usabilla methods or properties are triggered using a data mapping in the Usabilla Remote Command tag, by using the following Tealium commands:

          Remote Command Usabilla Method/Property
          initialize initialize()
          sendevent sendEvent()
          debugenabled debugEnabled
          displaycampaigns canDisplayCampaigns
          loadfeedbackform loadFeedbackForm()
          preloadfeedbackforms preloadFeedbackForms()
          removecachedforms removeCachedForms()
          dismissautomatically dismissAutomatically
          setcustomvariable customVariables
          resetcampaigndata resetCampaignData()

          Since the Usabilla SDK is integrated with the Tealium SDK, you may trigger any native Usabilla functionality given the corresponding tag configuration.

          SDK Setup

          Initialize

          The Usabilla SDK is initialized automatically upon launch. The Usabilla API key is set in the tag configuration.

          Remote Command Usabilla Method
          initialize initialize()

          Usabilla Developer Guide: Initial SDK Setup

          • iOS
          • Android

          Debug

          Remote Command Usabilla Property
          debugenabled debugEnabled
          Parameter Type
          debugEnabled (required) Bool

          Usabilla Developer Guide: Initial SDK Setup

          • iOS
          • Android

          Campaign Toggling

          Remote Command Usabilla Property
          displaycampaigns canDisplayCampaigns
          Parameter Type
          canDisplayCampaigns (required) Bool

          Usabilla Developer Guide: Campaign Toggling

          • iOS

          Campaign toggling is not available for Android

          Targeting Options

          Send Events

          Remote Command Usabilla Method
          sendevent sendEvent()
          Parameter Type
          event (required) String

          Usabilla Developer Guide: Targeting Options

          • iOS
          • Android

          Set Custom Variables

          Remote Command Usabilla Property
          setcustomvariable customVariables
          Parameter Type
          custom.### (required) String

          Usabilla Developer Guide: Set Custom Variables

          • iOS
          • Android

          Forms

          Load Feedback Form

          Remote Command Usabilla Method
          loadfeedbackform loadFeedbackForm
          Parameter Type Example
          formId (required) String
          fragmentId (Android only) Integer R.id.activity_main

          Usabilla Developer Guide: Load Feedback Form

          • iOS
          • Android

          Preload Feedback Forms

          Remote Command Usabilla Method
          preloadfeedbackforms preloadFeedbackForms
          Parameter Type
          formIds (required) [String]

          Usabilla Developer Guide: Preload Feedback Forms

          • iOS
          • Android

          Remove Cached Forms

          Remote Command Usabilla Method
          removecachedforms removeCachedForms

          Usabilla Developer Guide: Remove Cached Forms

          • iOS
          • Android

          Dismiss Automatically

          Remote Command Usabilla Property
          dismissautomatically dismissAutomatically
          Parameter Type
          dismissAutomatically (required) Bool

          Usabilla Developer Guide: Manual Dismiss

          • iOS
          • Android

          Reset

          Remote Command Usabilla Property
          resetcampaigndata resetCampaignData

          Usabilla Developer Guide: Resetting All Campaigns

          • iOS
          • Android
          Remote Command: Kochava

           
          • Mobile
          • Getting Started
            • Overview
            • Quick Start Guide
            • Mobile Concepts
            • Client-Side
            • Server-Side
            • Tracking Webviews
            • Data Layer
            • Consent Management
            • Event Batching
            • User Location and Geofencing
            • Deep Links
            • Timed Events
            • Trace
            • Hosted Data Layer
            • Feature Comparison
            • Troubleshooting
          • Remote Commands
            • Overview
            • How It Works
            • Integrations
              • AppsFlyer
              • Braze
              • Contentsquare
              • Facebook
              • Firebase
              • Kochava
              • Usabilla
          • Android (Java)
            • Overview
            • Install
            • Track
            • Data Layer
            • Data Management
            • Consent Management
            • Module List
              • Ad Identifier Module
              • Crash Reporter Module
              • Install Referrer Module
              • Lifecycle Tracking Module
              • Location Module
              • Optimizely X Tracking Module
            • Android TV
            • Android Wear
            • API Reference
              • ConsentManager
              • DataSources
              • Lifecycle
              • Tealium
              • Tealium.Config
              • TealiumLocation
            • Release Notes
          • Android (Kotlin)
            • Overview
            • Install
            • Track
            • Data Layer
            • Consent Management
            • Identity Resolution
            • Module List
              • Collect Module
              • Collectors Module
              • Crash Reporter Module
              • Install Referrer Module
              • Lifecycle Tracking Module
              • Location Manager Module
              • Tag Management Dispatcher Module
              • Visitor Service Module
            • Android TV
            • API Reference
              • ConsentCategory
              • ConsentManager
              • CurrentVisit
              • DataLayer
              • Lifecycle
              • LocationManager
              • Tealium
              • TealiumConfig
              • VisitorProfile
              • VisitorService
            • Release Notes
          • Cordova
            • Overview
            • Install
            • Track
            • Data Management
            • Module List
              • Ad Identifier Module
              • Crash Reporter Module
              • Install Referrer Module
            • API Reference
            • Release Notes
          • Flutter
            • Overview
            • Install
            • Track
            • Consent Management
            • Data Management
            • API Reference
            • Release Notes
          • iOS (Objective-C)
            • Overview
            • Install
            • Track
            • Data Layer
            • Data Management
            • Consent Management
            • Tag Management
            • Module List
              • Lifecycle Tracking Module
              • Optimizely X Tracking Module
            • tvOS
            • watchOS
            • API Reference
            • Release Notes
          • iOS (Swift) 1.x
            • Overview
            • Install
            • Track
            • Data Layer
            • Data Management
            • App Extensions
            • Identity Resolution
            • Consent Management
            • Modules
            • Module List
              • AppData Module
              • Attribution Module
              • AutoTracking Module
              • Collect Module
              • Connectivity Module
              • CrashReporter Module
              • DataSource Module
              • DefaultStorage Module
              • Delegate Module
              • DeviceData Module
              • DispatchQueue Module
              • FileStorage Module
              • Lifecycle Module
              • Location Module
              • Logger Module
              • PersistentData Module
              • RemoteCommands Module
              • TagManagement Module
              • VisitorService Module
              • VolatileData Module
            • Feature Comparison
            • Working with Objective-C
            • API Reference
              • TealiumConfig
              • TealiumConsentCategories
              • TealiumConsentManagerDelegate
              • TealiumConsentManager
              • TealiumInstanceManager
              • TealiumPersistentData
              • TealiumVolatileData
              • Tealium
            • Release Notes
          • iOS (Swift) 2.x
            • Overview
            • Install
            • Track
            • Data Layer
            • Consent Management
            • App Extensions
            • Identity Resolution
            • Modules
            • Module List
              • AppData Module
              • Attribution Module
              • AutoTracking Module
              • Collect Module
              • Connectivity Module
              • CrashReporter Module
              • DeviceData Module
              • Lifecycle Module
              • Location Module
              • RemoteCommands Module
              • TagManagement Module
              • VisitorService Module
            • Working with Objective-C
            • API Reference
              • Tealium
              • TealiumConfig
              • TealiumConsentCategories
              • TealiumConsentManager
              • TealiumDataLayer
              • TealiumInstanceManager
            • Release Notes
          • React Native
            • Overview
            • Install
            • Track
            • API Reference
            • Release Notes
          • Unity
            • Overview
            • Install
            • Track
            • API Referencee
          • Xamarin
            • Overview
            • Install
            • Track
            • Data Management
            • Consent Management
            • API Reference
            • Release Notes
          • Web
          • AMP
            • Overview
            • Install
            • Track
            • Data Layer
          • Angular
            • Overview
            • Install
            • Track
            • API Reference
          • Google Tag Manager
            • Overview
            • Install
            • Data Layer
          • JavaScript (Web)
            • Overview
            • Install
            • Track
            • Data Layer
            • Universal Data Object (utag_data)
            • Universal Tag (utag.js)
            • Data Layer Object (b)
            • Single-Page Applications
            • Settings
            • Debugging
            • API Reference
              • Cookie Functions
              • GDPR Functions
              • Tracking Functions
              • Utility Functions
            • Release Notes
          • Server
          • C#
            • Overview
            • Install
            • Track
            • Data Layer
            • API Reference
            • Release Notes
          • HTTP API
            • Overview
            • Endpoint
            • Data Layer
          • Java
            • Overview
            • Install
            • Track
            • API Reference
            • Release Notes
          • Node
            • Overview
            • Install
            • Track
            • API Reference
          • Python
            • Overview
            • Install
            • Track
            • API Reference
          • Roku
            • Overview
            • Install
            • Track
            • API Reference
          • Ruby
            • Overview
            • Install
            • Track
            • API Reference

          Was this article helpful?

          This page was last updated: November 11, 2020       Thank you for your feedback!
          • Platforms
          • Partners
          • Forums
          • Mobile
          • Getting Started
          • Remote Commands
          • Android (Java)
          • Android (Kotlin)
          • Cordova
          • Flutter
          • iOS (Objective-C)
          • iOS (Swift) 1.x
          • iOS (Swift) 2.x
          • React Native
          • Unity
          • Xamarin
          • Web
          • AMP
          • Angular
          • Google Tag Manager
          • JavaScript (Web)
          • Server
          • C#
          • HTTP API
          • Java
          • Node
          • Python
          • Roku
          • Ruby