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:

1. The Kochava native SDK
2. The remote commands module that wraps the Kochava methods
3. 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

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.

Manual (iOS)

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:

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

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

3. Set the remoteAPIEnabled configuration flag to true

Manual (Android)

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:

1. Add flatDir to your project root build.gradle file:

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

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

3. 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.

Android (Kotlin)

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));

var tealium = Tealium.create(TEALIUM_MAIN, config) {
    val kochava = KochavaRemoteCommand(application);
    remoteCommands?.add(kochava, filename = "kochava.json");
}

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

var tealium = Tealium.create(TEALIUM_MAIN, config) {
    val kochava = KochavaRemoteCommand(application);
    remoteCommands?.add(kochava);
}

Android (Java)

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

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

iOS (Swift)

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.remoteAPIEnabled = true

tealium = Tealium(config: config) { _ in
    guard let remoteCommands = self.tealium?.remoteCommands else {
        return
    }
    let kochava = KochavaRemoteCommand(type: .local(file: "kochava"))
    remoteCommands.add(kochava)
}

var tealium : Tealium?
let config = TealiumConfig(account: "ACCOUNT",
                           profile: "PROFILE",
                           environment: "ENVIRONMENT",
                           dataSource: "DATASOURCE")
config.remoteAPIEnabled = true

tealium = Tealium(config: config) { _ in
    guard let remoteCommands = self.tealium?.remoteCommands else {
        return
    }
    let kochava = KochavaRemoteCommand()
    remoteCommands.add(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 via 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:

1. In the TealiumHelper.swift file, initialize an empty array of objects that conform to the TealiumRegistration protocol. For example:

   var pushMessagingHelpers = [TealiumRegistration]()
   

2. Initialize the KochavaInstance before the KochavaRemoteCommand

3. Append the KochavaInstance to the array described above

The following is full 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 via 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 desired location.

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

1. In the TealiumHelper.swift file, initialize an empty array of objects that conform to the TealiumDeepLinkable protocol. For example:

   var deepLinkHelpers = [TealiumDeepLinkable]()
   

2. Initialize the KochavaInstance before the KochavaRemoteCommand

3. Append the KochavaInstance to the array described above.

The following is full example of the enhanced deep linking integration:

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

The following Kochava methods are triggered using a data mapping in the Kochava Remote Command tag using the following Tealium commands:

iOS Remote Commands

Android Remote Commands

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.

For iOS, theKVAEvent.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:

• Kochava iOS SDK
• Kochava Android SDK

Initialize

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

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

Sleep Tracker

Invalidate (iOS)

Send Identity Link (iOS)

Send Custom Event (iOS)

Send Custom Event (iOS)