Remote Command: Kochava

Requirements

Kochava App GUID
One of these mobile libraries:
- Tealium for Android-Kotlin (1.0.0+)
- Tealium for Android-Java (5.9.0+)
- Tealium for iOS-Swift (2.1.0+)
One of these remote command integrations:
- Kochava Remote Command JSON File (Requires Android-Kotlin 1.0.0+ or iOS-Swift 2.1.0+)
- Kochava Remote Command tag in Tealium iQ Tag Management

How It Works

The Kochava integration uses three items:

The Kochava native SDK
The remote commands module that wraps the Kochava methods
Either the JSON configuration file or Remote Command tag that translates event tracking into native Kochava calls

Adding the Kochava remote command module to your app automatically installs and builds the required Kochava libraries, without having to add vendor-specific code to your app. If you are using a dependency manager installation, there is no need to install the Kochava 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

In your Xcode project, select File > Add Packages… > Add Package Dependency.
Enter the repository URL: https://github.com/tealium/tealium-ios-kochava-remote-command.
Configure the version rules. Typically, Up to next major is recommended. If the current TealiumKochava version does not appear in the list, then reset your Swift package cache.
Select the TealiumKochava module to install, and select the app target you want the module to be installed in.

If your project has more than one app target and needs TealiumKochava module in more app targets, you have to manually add them in the Frameworks, Libraries, and Embedded Content section.

To install TealiumKochava in additional app targets:

Select your Xcode project in the Project Navigator.
In your Xcode project, select the app target under the TARGETS section.
Navigate to General > Frameworks, Libraries & Embedded Content and select the TealiumKochava module to add it to your app target.

To add additional modules from the Tealium Swift library, follow the Swift Package Manager instructions.

Remove tealium-swift and pod "KochavaTrackeriOS" if they already exist your Podfile. The dependency for tealium-swift is already included in the TealiumKochava framework.
Add the following dependency to your Podfile:
```
pod "TealiumKochava"
```
The TealiumKochava pod includes the following TealiumSwift dependencies:
```
'tealium-swift/Core'
'tealium-swift/RemoteCommands'
'tealium-swift/TagManagement'
```
Import the modules TealiumSwift and TealiumKochava in your TealiumHelper file, and any other files that access the Tealium class, or the Kochava Remote Command.

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

Add the following dependency to your Cartfile:

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

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

Install Tealium for Android (Kotlin) or Tealium for Android (Java) and add the Tealium Maven URL to your project’s top-level build.gradle file, if you haven’t done so already.
```
allprojects {
  repositories {
    mavenCentral()
    maven {
      url "https://maven.tealiumiq.com/android/releases/"
    }
  }
}
```
Import both the Kochava SDK and Tealium-Kochava remote commands by adding the following dependencies in your app project’s build.gradle file:
```
dependencies {
      implementation 'com.tealium.remotecommands:kochava:1.0.0'
}
```

Manual Installation

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

Install the Kochava SDK, if you haven’t already done so.
Clone the Tealium iOS Kochava remote command repo and drag the files within the Sources folder into your project.
Set the remoteAPIEnabled configuration flag to true.

The manual installation for Kochava remote commands requires Tealium for Android (Kotlin) or Tealium for Android (Java) to be installed.

To install the Kochava remote commands for your Android project:

Add flatDir to your project root build.gradle file:

allprojects {
      repositories {
        mavenCentral()
        flatDir {
            dirs 'libs'
        }
      }
}

Add tealium-kochava.aar to <PROJECT_ROOT>/<MODULE>/libs.

Add the Tealium library dependency to your build.gradle file:

dependencies {
      implementation(name:'tealium-kochava', ext:'aar')
}

Initialize

For all Tealium libraries, register the Kochava mobile remote commands when you initialize.

Initialize remote commands with a JSON configuration file or the Remote Command tag for Tealium’s iOS (Swift) library:

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
    }

    // Webview Tag
    let kochava = KochavaRemoteCommand() 

    // Local JSON
    //let kochava = KochavaRemoteCommand(type: .local(file: "kochava"))

    // Remote JSON 
    //let kochava = KochavaRemoteCommand(type: .remote(url: "https://some.domain.com/kochava.json")) 

    remoteCommands.add(kochava)
}

Initialize remote commands with a JSON configuration file or the Remote Command tag for Tealium’s Kotlin library:

val config = TealiumConfig(application,
        "ACCOUNT",
        "PROFILE",
        Environment.DEV,
        dispatchers = mutableSetOf(Dispatchers.RemoteCommands, Dispatchers.TagManagement));
val kochava = KochavaRemoteCommand(application);

var tealium = Tealium.create(TEALIUM_MAIN, config) {

    // Webview Tag
    remoteCommands?.add(kochava); 

    // Local JSON
    //remoteCommands?.add(kochava, filename = "kochava.json"); 

    // Remote JSON
    //remoteCommands?.add(kochava, remoteUrl = "https://some.domain.com/kochava.json"); 
}

Initialize remote commands with the Remote Command tag for Tealium’s Android (Java) library:

RemoteCommand kochava = new KochavaRemoteCommand(application);
teal.addRemoteCommand(kochava);

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 installation. Edit the mappings as needed.

{
  "config": {
    "app_guid": "test app guid",
    "log_level": "debug",
    "app_tracking_transparency_enabled": false,
    "limit_ad_tracking": true,
    "identity_link_ids": {
        "userID": "CUST123",
        "userName": "Bob"
    }
  },
  "mappings": {
      "event_title": "custom_event_name",
      "achievement_id": "custom.achievement_id",
      "ad_network_name": "custom.ad_network_name",
      "campaign_id": "event.ad_campaign_id",
      "campaign": "event.ad_campaign_name",
      "cart_add_location": "event.item_added_from",
      "checkout_option": "custom.checkout_option",
      "checkout_step": "custom.checkout_step",
      "content": "event.content_id",
      "content_type": "event.content_type",
      "coupon": "custom.coupon",
      "currency_code": "event.currency",
      "customer_id": "event.user_id,identity_link_ids.userID",
      "device_type": "event.ad_device_type",
      "end_date": "event.end_date",
      "flight_number": "custom.flight_number",
      "game_character": "custom.character",
      "group_name": "event.ad_group_name",
      "guest_checkout": "event.checkout_as_guest",
      "level": "event.level",
      "number_nights": "custom.number_nights",
      "number_pax": "custom.number_passengers",
      "number_rooms": "custom.number_rooms",
      "order_id": "event.order_id",
      "order_shipping_amount": "custom.shipping",
      "order_tax_amount": "custom.tax",
      "order_total": "custom.total",
      "product_brand": "custom.brand",
      "product_category": "custom.category",
      "product_id": "custom.product_id",
      "product_name": "event.name",
      "product_quantity": "event.quantity",
      "product_unit_price": "event.price",
      "rating": "event.rating_value",
      "score": "event.score",
      "search_keyword": "event.search_term",
      "search_results": "event.results",
      "signup_method": "event.registration_method",
      "start_date": "event.start_date",
      "travel_destination": "event.destination",
      "travel_class": "custom.travel_class",
      "travel_origin": "event.origin",
      "username": "event.user_name,identity_link_ids.userName"
    },
  "commands": {
      "launch": "initialize",
      "user_login": "custom,sendidentitylink",
      "user_register": "registrationcomplete",
      "share": "custom",
      "show_offers": "adclick,adview",
      "join_group": "custom",
      "travel_order": "purchase",
      "unlock_achievement": "achievement",
      "level_up": "levelcomplete",
      "stop_tutorial": "tutorialcomplete",
      "record_score": "custom",
      "category": "view",
      "product": "view",
      "cart_add": "addtocart",
      "wishlist_add": "addtowishlist",
      "checkout": "checkoutstart",
      "rating": "rating",
      "search": "search",
      "screen_veiw": "view",
      "email_signup": "subscribe",
      "order": "purchase",
      "disable_analytics": "sleeptracker,invalidate"
  }
}

Push Message Tracking (iOS)

The Tealium Swift library includes a TealiumRegistration protocol for handling push message tracking through Tealium and the Kochava Remote Command. We conform to this protocol in the wrapper class KochavaInstance which is used to send push message authorization events, push message open events, and to uninstall tracking. We recommend taking advantage of the push message tracking capability.

The following steps integrate push message tracking for your iOS project:

In the TealiumHelper.swift file, initialize an empty array of objects that conform to the TealiumRegistration protocol. For example:
```
var pushMessagingHelpers = [TealiumRegistration]()
```
Initialize the KochavaInstance before the KochavaRemoteCommand
Append the KochavaInstance to the array described above

The following is an example of the push message tracking integration:

var pushMessagingHelpers = [TealiumRegistration]()

//...

teal = Tealium(config: config) { responses in
  guard let remoteCommands = self.tealium?.remoteCommands() else {
        return
  }
  let kochavaInstance = KochavaInstance()
  let kochavaRemoteCommand = KochavaRemoteCommand(kochavaInstance: kochavaInstance)
  remoteCommands.add(kochavaRemoteCommand)
  self.pushMessagingHelpers.append(kochavaInstance)
}

To see the entire TealiumHelper.swift file, explore the Kochava Remote Command Example App. To send an event to Kochava once a user has registered for notifications, opened a push message, or uninstalled the app, see the file AppDelegate.swift.

For more information about Kochava’s push message tracking, see the Kochava iOS push notification documentation.

Enhanced Deep Linking (iOS)

The Tealium Swift Library includes a TealiumDeepLinkable protocol for handling your deep links through Tealium and the Kochava Remote Command. We conform to this protocol in wrapper class KochavaInstance which is used to send .deepLink events before rerouting your user to the location you want.

The following steps integrate enhanced deep linking for your iOS project:

In the TealiumHelper.swift file, initialize an empty array of objects that conform to the TealiumDeepLinkable protocol. For example:
```
var deepLinkHelpers = [TealiumDeepLinkable]()
```
Initialize the KochavaInstance before the KochavaRemoteCommand
Append the KochavaInstance to the array described above.

The following is full example of the enhanced deep linking integration:
```swift var deepLinkHelpers = TealiumDeepLinkable

  //...

  teal = Tealium(config: config) { responses in
    guard let remoteCommands = self.tealium?.remoteCommands() else {
      return
    }
    let kochavaInstance = KochavaInstance()
    let kochavaRemoteCommand = KochavaRemoteCommand(kochavaInstance: kochavaInstance)
    remoteCommands.add(kochavaRemoteCommand)
    self.deepLinkHelpers.append(kochavaInstance)
  }
  ```

To see the entire TealiumHelper.swift file, explore the Kochava Remote Command Example App.

To send an event to Kochava once a user has registered for notifications, opened a push message, or uninstalled the app, see the file AppDelegate.swift.

For more information about Kochava’s enhanced deep linking, see the Kochava iOS documentation.

Supported Methods

We map a command to each Kochava method. To trigger a Kochava method, pass the corresponding command in the specified format.

iOS Remote Commands

iOS Remote Command	Kochava Method
`initialize`	`start()`
`sleepTracker`	`sleepTracker (property on the KochavaTracker.shared object)`
`invalidate`	`invalidate()`
Any of the below event names	`sendEvent()`
`sendIdentityLink`	`sendIdentityLink()`
Called manually in `AppDelegate` within `didReceiveRemoteNotification`	`sendEvent() - event type: .pushOpened`
Called manually in `AppDelegate` within `didRegisterForRemoteNotificationsWithDeviceToken` using `TealiumRegistration` protocol (`registerPushToken()` method)	`addRemoteNotificationsDeviceToken()`
Called manually in `AppDelegate` within `continue userActivity` using `TealiumDeeplinkable` protocol	`KVADeeplink.process()` and/or `sendEvent() - event type: .deepLink`

Android Remote Commands

Android Remote Command	Kochava Method
`configure`	`configure()`
`setsleep`	`setSleep()`
Any of the below event names	`sendEvent()`

Standard Event Names

The following standard event command names are supported with the trackEvent method. When a command is sent, and all required variables are mapped and defined for the event, then the command is automatically triggered in the Kochava SDK.

Remote Command	Kochava Event Name (iOS)	Kochava Event Name (Andriod)
`achievement`	`KVAEventType.achievement`	`Commands.ACHIEVEMENT`
`addToCart`	`KVAEventType.addToCart`	`Commands.ADD_TO_CART`
`addToWishlist`	`KVAEventType.addToWishList`	`Commands.Add_TO_WISH_LIST`
`registrationComplete`	`KVAEventType.registrationComplete`	`Commands.REGISTRATION_COMPLETE`
`tutorialComplete`	`KVAEventType.tutorialComplete`	`Commands.TUTORIAL_COMPLETE`
`levelComplete`	`KVAEventType.levelComplete`	`Commands.LEVEL_COMPLETE`
`checkoutStart`	`KVAEventType.checkoutStart`	`Commands.CHECKOUT_START`
`purchase`	`KVAEventType.purchase`	`Commands.PURCHASE`
`subscribe`	`KVAEventType.subscribe`	`Commands.SUBSCRIBE`
`startTrial`	`KVAEventType.startTrial`	`Commands.START_TRIAL`
`rating`	`KVAEventType.rating`	`Commands.RATING`
`search`	`KVAEventType.search`	`Commands.SEARCH`
`adView`	`KVAEventType.adView`	`Commands.AD_VIEW`
`view`	`KVAEventType.view`	`Commands.VIEW`
`pushOpened`	`KVAEventType.pushOpened`	requires `customEventNameString` in mappings
`pushRecieved`	`KVAEventType.pushReceived`	requires `customEventNameString` in mappings
`consentGranted`	`KochavaEventTypeEnumConsentGranted`	requires `customEventNameString` in mappings
`adClick`	`KVAEventType.adClick`	requires `customEventNameString` in mappings
`custom`	`KVAEventType.custom` (`customEventNameString` required in mappings)	requires `customEventNameString` in mappings

For iOS, the KVAEvent.deepLink event needs to be sent in the AppDelegate using either the native KVAEvent.send() method or the TealiumDeepLinkable protocol.

SDK Setup

Learn more about the Kochava SDK Setup:

Initialize

The Kochava SDK is initialized automatically upon launch. The Kochava App GUID is set in the Tealium remote command configuration.

Remote Command	Kochava Method
`initialize`	`start()`

There are several configuration options available for the Kochava Remote Command tag. If any of the below are set on launch, they are sent during the configure() method.

Configuration Options

Name	TiQ Variable Mapping	Description	Type
Log Level	`log_level`	The log level for Kochava output in the console: `none`, `error`, `warn`, `info`, `debug`, `trace` (Learn more about log levels)	`String`
Retrieve Attribution Data	`retrieve_attribution_data`	Boolean for setting a delegate/listener that gets the attribution data when ready. In `TealiumKochava` the `attributionDictionary` is set to Volatile Storage, and sent a `track` call with a `tealium_event` of `attribution`. The delegate/listener method may be added in `TealiumKochavaTracker` (Learn more about retrieving attribution)	`Bool`
Identity Link IDs	`identity_link_ids`	Links different identities together in the form of key-value pairs (Learn more about identity linking)	`Int`
Limit Ad Tracking	`limit_ad_tracking`	Limits ad tracking at the application level if enabled (Default: `false`)	`Bool`
Enable App Tracking Transparency (iOS 14+)	`app_tracking_transparency_enabled`	Enables Kochava’s automatic implementation of App Tracking Transparency (iOS 14+) if enabled. (Default: `false`)	`Bool`

Sleep Tracker

Remote Command	Kochava Method
`sleeptracker` (iOS)	`sleepTracker` (`KochavaTracker.shared` object property)
`setsleep` (Android)	`setSleep()`

Parameter	Type
`sleep` (required)	`Bool`

Invalidate (iOS)

Remote Command	Kochava Method
`invalidate`	`invalidate()`

Send Identity Link (iOS)

Remote Command	Kochava Method
`sendidentitylink`	`sendIdentityLink()`

Parameter	Type
`identityLinkIds` (required)	Key-value pairs

Send Custom Event (iOS)

Remote Command	Kochava Method
Standard Event Names	`send()`

Parameter	Type
`event_parameters` (optional)	Key-value pairs

Send Custom Event (iOS)

Remote Command	Kochava Method
`custom`	`sendCustom()`

Parameter	Type
`custom_event_name` (required)	`String`
`info_dictionary` (optional)	Key-value pairs