Remote Command: Usabilla

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:

The Usabilla native SDK
The remote commands module that wraps the Usabilla methods
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:

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

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'

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:

Remove tealium-swift from your Cartfile. The dependency for tealium-swift is already included in the TealiumUsabilla framework.
Remove the following line if it exists in your Cartfile:
```
github "usabilla/usabilla-u4a-ios-swift-sdk"
```

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:

Install Tealium for Android (Kotlin) or Tealium for Android (Java), if you haven’t done so already.
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:

Install the Usabilla SDK, if you haven’t already done so.
Clone the Tealium iOS Usabilla remote command repo and drag the files within the Sources folder into your project.
Add Dispatchers.RemoteCommands as a dispatcher
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

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