Kochava Destination

Segment makes it easy to send your data to Kochava (and lots of other destinations). Once you've tracked your data through our open source libraries we'll translate and route your data to Kochava in the format they understand. Learn more about how to use Kochava with Segment.

Getting Started

The first step is to make sure Kochava supports the source type and connection mode you’ve chosen to implement. You can learn more about what dictates the connection modes we support here.

WebMobileServer
📱 Device-based
☁️ Cloud-based
  1. If you have not already, create your app within the Kochava dashboard. Check out Kochava’s documentation for information on creating your app.
  2. From your Segment UI’s Destinations page click on “Add Destination”.
  3. Search for “Kochava” within the Destinations Catalog and confirm the Source you’d like to connect to.
  4. In the Kochava app, grab your Kochava App GUID (Globally Unique Identifier)
  5. Copy the Kochava GUID into the Segment Destinations Settings UI under “API key”.

Additional information from Kochava on setting up your first campaign within Kochava.

Track

If you haven’t had a chance to review our spec, please take a look to understand what the Track method does. An example call would look like:

[[SEGAnalytics sharedAnalytics] track:@"Item Purchased"
                           properties:@{ @"item": @"Sword of Heracles", @"revenue": @2.95 }];

Kochava is able to accommodate any post-install track event that is passed into its system. Events, when received for the first time, will auto provision into the Kochava dashboard. There is no need to create / provision the post-install track event ahead of time. When enabling Kochava in the Segment dashboard, you should expect to see any / all actions you’re tracking with Segment appear in your Kochava account.

context.device.type (has value of ‘ios’ or ‘android’), context.device.advertising_id (IDFA on iOS and adID on Android) and context.device.id are required in all calls to Kochava.

To automatically collect context.device.advertising_id, on Android you must include the Google Mobile Ads component of Google Play services as described here, and on iOS you must include the iAd framework.

If making calls outside of Segment’s iOS or Android library (eg post-install events sent from a server-side library), you’ll need to ensure that you collect and send context.device.type, context.device.advertising_id and context.device.id.

Note that if you are sending data from mobile devices using one of our mobile libraries as well as server-side, context.device.id and context.device.advertising_id need to be the same for the same user regardless of where the data originates. Below is a Ruby example of how to pass the required context information in the track call.

Analytics.track(
  user_id: '019mr8mf4r',
  event: 'Subscription Charge',
  properties: {
    subscription_type: 'Premium',
    revenue: '9.99'
  },
  context: {
    device: {
      id: '176779B9-8C07-4E53-B3EA-ABBFAA40C829',
      advertising_id: '017D76B5-85F8-4E3C-8CCE-8B29CCEACB1D',
      type: 'ios' # or 'android'
    }
  }
)

Install Attributed Postback

To create a Kochava-Certified Postback that will send campaign information to Segment after attributing an Application Installed event, follow Kochava’s Postback Setup documentation.

Apple Search Ads

To get iAD attribution data into Kochava, you must include the analytics-ios-iads-attribution dependency and version 3.6.0 or higher of the Analytics SDK.

To install it, simply add the following line to your Podfile:

pod "Analytics"
pod "Analytics-iAds-Attribution"

Then import the header and initialize the configuration:

#import <Analytics-iAds-Attribution/SEGADTracker.h>

// Initialize the configuration as you would normally.
SEGAnalyticsConfiguration *configuration = [SEGAnalyticsConfiguration configurationWithWriteKey:@"YOUR_WRITE_KEY"];
...

// Configure the client with the iAD middleware to attach iAd properties.
configuration.middlewares = @[ [SEGADTracker middleware] ];

[SEGAnalytics setupWithConfiguration:configuration];

When it is able to retrieve iAd information, it will augment all track events. The attribution information is transformed to Segment context this way:

[analytics track:@"Application Installed",
    properties: nil,
    options: @{
      @"context" : @{
        @"campaign" : @{
          @"provider" : @"Apple",
          @"click_date" : attributionInfo[@"iad-click-date"],
          @"conversion_date" : attributionInfo[@"iad-conversion-date"],
          @"source" : @"iAd",
          @"name" : attributionInfo[@"iad-campaign-name"],
          @"content" : attributionInfo[@"iad-keyword"],
          @"ad_creative" : attributionInfo[@"iad-org-name"],
          @"ad_group" : attributionInfo[@"iad-adgroup-name"],
          @"id" : attributionInfo[@"iad-campaign-id"],
          @"ad_group_id" : attributionInfo[@"iad-adgroup-id"]
        }
      }
    }];

Because this information in passed through the context object, this will not be received by other downstream integrations, unless explicitly mapped. Kochava is currently the only integration which supports Apple Search Ads.

Troubleshooting

advertisingId is string of 0s

This occcurs when the user has limited ad tracking enabled on their iOS mobile device.


Personas

You can send computed traits and audiences generated through Segment Personas to this destination as a user property. To learn more about Personas, reach out for a demo.

For user-property destinations, an identify call will be sent to the destination for each user being added and removed. The property name will be the snake_cased version of the audience name you provide with a true/false value. For example, when a user first completes an order in the last 30 days, we will send an identify call with the property order_completed_last_30days: true, and when this user no longer satisfies we will set that value to false.

When the audience is first created an identify call is sent for every user in the audience. Subsequent syncs will only send updates for those users which were added or removed since the last sync.

Settings

Segment lets you change these destination settings via your Segment dashboard without having to touch any code.

API Key

Get your Kochava App GUID from your Kochava user interface.


If you have any questions or see anywhere we can improve our documentation, please let us know or kick off a conversation in the Segment Community!