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
andpod "Usabilla"
if they already exist your Podfile. The dependency fortealium-swift
is already included in theTealiumUsabilla
framework.Add the following dependency to your Podfile:
pod "TealiumUsabilla"
The
TealiumUsabilla
pod includes the followingTealiumSwift
dependencies:'tealium-swift/Core' 'tealium-swift/TealiumDelegate' 'tealium-swift/TealiumRemoteCommands' 'tealium-swift/TealiumTagManagement'
Import the modules
TealiumSwift
andTealiumUsabilla
in yourTealiumHelper
file, and any other files that access theTealium
class or the Usabilla remote command.
To install Usabilla remote commands for iOS using Carthage:
Remove
tealium-swift
from your Cartfile. The dependency fortealium-swift
is already included in theTealiumUsabilla
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 dispatcherSet the
remoteAPIEnabled
configuration flag totrue
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 theHttpClient
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 theUsabillaReadyCallback
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’sFragmentManager
to be kept up-to-date and monitored usingandroid.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). Twoandroid.content.BroadcastReceiver
s 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 theHttpClient
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 theUsabillaReadyCallback
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’sFragmentManager
to be kept up-to-date and monitored usingandroid.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). Twoandroid.content.BroadcastReceiver
s 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 theHttpClient
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 theUsabillaReadyCallback
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’sFragmentManager
to be kept up-to-date and monitored usingandroid.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). Twoandroid.content.BroadcastReceiver
s 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
Debug
Remote Command | Usabilla Property |
---|---|
debugenabled |
debugEnabled |
Parameter | Type |
---|---|
debugEnabled (required) |
Bool |
Usabilla Developer Guide: Initial SDK Setup
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
Set Custom Variables
Remote Command | Usabilla Property |
---|---|
setcustomvariable |
customVariables |
Parameter | Type |
---|---|
custom.### (required) |
String |
Usabilla Developer Guide: Set Custom Variables
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
Preload Feedback Forms
Remote Command | Usabilla Method |
---|---|
preloadfeedbackforms |
preloadFeedbackForms |
Parameter | Type |
---|---|
formIds (required) |
[String] |
Usabilla Developer Guide: Preload Feedback Forms
Remove Cached Forms
Remote Command | Usabilla Method |
---|---|
removecachedforms |
removeCachedForms |
Usabilla Developer Guide: Remove Cached Forms
Dismiss Automatically
Remote Command | Usabilla Property |
---|---|
dismissautomatically |
dismissAutomatically |
Parameter | Type |
---|---|
dismissAutomatically (required) |
Bool |
Usabilla Developer Guide: Manual Dismiss
Reset
Remote Command | Usabilla Property |
---|---|
resetcampaigndata |
resetCampaignData |
Usabilla Developer Guide: Resetting All Campaigns