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

Manual Installation

Initialize

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

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

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

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 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 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 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:
```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

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, 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:

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