Kochava Post-Install Event Setup

Feature Summary: This document describes the recommended approach to integrate with the Kochava system to track post-install events. It is important to follow these API instructions in order to avoid data corruption and maximize the effectiveness of Kochava in your environment.

NOTE: For examples of post-install events, refer to our Post-Install Event Examples support documentation.

BEST PRACTICES: If strict authentication rules are being utilized, ensure that the procedures and policies within the Kochava Install Authentication Integration support documentation have been followed.

Google DMA Details:

Consent Signals Object —

S2S clients need to add the following object to the data object for events:

   "gdpr_privacy_consent":{
      "gdpr_applies":1,
      "tc_string":"some example string",
      "ad_user_data":1,
      "ad_personalization":1
   }

Parameter Details —

Key	Required	Notes
gdpr_privacy_consent	Yes	Object to support Google’s Consent Signals requirement.
gdpr_applies	Yes/No	Required if not passing user IP.
tc_string	Yes/No	Required if not passing ad_user_data & ad_personalization.
ad_user_data	Yes/No	Required if not passing tc_string
ad_personalization	Yes/No	Required if not passing tc_string

Post-Install Event Example:

{
   "data":{
      "usertime":1521574016,
      "app_version":"1.0.0",
      "device_ver":"",
      "device_ids":{
         "idfa":"{idfa}"
      },
      "device_ua":"Mozilla/5.0 (iPhone; CPU iPhone OS 8_0 like Mac OS X) AppleWebKit/534.46 (KHTML, like Gecko) Version/5.1 Mobile/9A334 Safari/7534.48.3",
      "event_name":"SubscriptionTest",
      "origination_ip":"104.219.46.66",
      "currency":"USD",
      "gdpr_privacy_consent":{
         "gdpr_applies":1,
         "tc_string":"some example string",
         "ad_user_data":1,
         "ad_personalization":1
      },
      "event_data":{
         "id":"123",
         "name":"Skis",
         "sum":150
      }
   },
   "action":"event",
   "kochava_app_id":"<APP GUID HERE>",
   "kochava_device_id":"<CUSTOM VALUE>"
}

iOS14+ Event Tracking:

With iOS14 Apple introduced the App Tracking Transparency framework, requiring that all apps prompt their users for consent to be tracked. If consent is not granted, the IDFA will not available. Kochava will respect the ATT framework by collecting the end users app_tracking_transparency response and timestamp of the response with our native iOS14 SDK.

Server to Server clients will need to include the indicated key-value pairs on all event payloads for any events coming from OS version iOS14 or higher.

WARNING: If the app_tracking_transparency flag is not sent on events for these users, Kochava will assume that consent was not granted, and we will drop the IDFA server side.

Install and Startup Tracking

To track the installation and startup of your application, please refer to the Server-to-Server Install Notification Integration Guide. Once Kochava has registered an install for a device, features can be tracked via server-to-server API according to the specifications provided here.

Post-Install Event API

To send a usage event from your application, call the following endpoint with a POST payload containing the desired JSON elements.

http://control.kochava.com/track/json

WARNING: Advertisers using a Server-to-Server integration should format payloads so that Kochava can parse the OS version, either by sending the full User Agent string or sending the device_ver in accordance with our support documentation.

JSON Property	Description	Req.	iOS 14+ Only
kochava_app_id	This is the unique application ID used to represent the app.	Yes
app_version	A string representation of the application version number.	No
kochava_device_id	kochava_device_id should be sent as a unique string that is consistent for each instance of the app on a single device. This will allow Kochava to associate data correctly when a device_id is not available. In the case that there will always be a device_id present and installs will always be sent before post-install events, kochava_device_id can be sent as an empty string. .	Yes
device_ids	This can be the IDFA, Android ID or a custom variant. You must submit at least one identifier within the device_id object, and may submit more than one.	Yes
action	Action associated to the API event.	Yes
origination_ip	The IP address of the device on install.	Yes
device_ver	Send the device_ver as an empty string, example “device_ver”: “”.	Yes
device_ua	A string representation of the device user agent as provided by the client. Please ensure that this is URL-encoded. This string is useful when campaigns require modeled attribution. (see iOS 14+ restrictions)	Yes
usertime	The time the event was completed by the user in Epoch format.	No
data	Each event is a JSON object – see examples. event_name -> A string representation of an event that has happened. event_data -> A corresponding value associated to the event_name. event_data is not required but useful for monetary tracking for correlated events (e.g. event_name -> “Level DLC Purchased” and event_value -> “20”).	Yes
att	Boolean indicating if iOS App Tracking Transparency was accepted or not. att = true — Tracking is authorized att = false — Tracking is not authorized	Yes	✔
att_time	The authorization time for iOS App Tracking Transparency.	No	✔
att_duration	The amount of time in seconds it took the user to respond to the ATT prompt.	No	✔
att_detail	The current ATTrackingManager.AuthorizationStatus .	No	✔

WARNING: kochava_app_id, kochava_device_id, device_ids, action, origination_ip, device_ver, device_ua, and data keys MUST be included on post-install event payloads. Otherwise, the post-install events will not be properly associated to the install, which has several implications, such as lack of attribution associated to the event and minimum time to reengagement windows not being applied.

NOTE: kochava_device_id can be sent as an empty string, as long as a device id is being sent and vice versa. device_ver can also be sent as an empty string. The parameters themselves indicated in the above table however, must be included in the post-install event payload.

BEST PRACTICES: Send the event data as a JSON object per the example below.

Sample Event Calls:

{
  "data": {
      "usertime": 1521574016,
      "app_version": "1.0.0",
      "device_ver": "",
      "device_ids": {
          "idfa": "{idfa}"
      },
      "device_ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 8_0 like Mac OS X) AppleWebKit/534.46 (KHTML, like Gecko) Version/5.1 Mobile/9A334 Safari/7534.48.3",
      "event_name": "SubscriptionTest",
      "origination_ip": "104.219.46.66",
      "currency": "USD",
      "event_data": {
          "id": "123",
          "name": "Skis",
          "sum": 150
          }
      },
  "action": "event",
  "kochava_app_id": "<APP GUID HERE>",
     "kochava_device_id": "<CUSTOM VALUE>"
}

iOS14+ Sample Event Calls:

{
    "data": {
        "app_tracking_transparency": {
            "att_time": 123456789,
            "att": true,
            "att_duration": 10,
            "att_detail": authorized
        },
        "usertime": 1521574016,
        "app_version": "1.0.0",
        "device_ver": "",
        "device_ids": {
            "idfa": "{idfa}"
        },
        "device_ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 8_0 like Mac OS X) AppleWebKit/534.46 (KHTML, like Gecko) Version/5.1 Mobile/9A334 Safari/7534.48.3",
        "event_name": "Test Event",
        "origination_ip": "104.219.46.66",
        "currency": "USD",
        "event_data": {
            "id": "123",
            "name": "Skis",
            "sum": 150
        }
    },
    "action": "event",
    "kochava_app_id": "<APP GUID HERE>",
    "kochava_device_id": "<CUSTOM VALUE>"
}

Device Specific Instructions

The information below details how to send data from specific devices to Kochava through the server-to-server integration.

Device	Sending a Usage Event Details
Roku	Send GetDeviceUniqueId() as String within the UDID parameter of the S2S feed.
LG	Send the LG device id (often referred to as LGUDID) should be passed under one of the supported device id key names such as: device_id or custom.

Server-to-Server without Device UA

In scenarios where the device user agent is not able to be included on the install and event payloads, the device version can be sent instead, which will enable Kochava to manufacture a device user agent and perform modeled (IP + UA) attribution. (see iOS 14+ restrictions)

For more information Server-to-Server without Device UA, refer to our support documentation.

Update IDFA

For iOS (includes iPad) and tvOS apps, you can notify Kochava when an IDFA became newly accessible for a given device. An example scenario where this may happen is if you are not showing the AppTrackingTransparency (ATT) prompt upon install, which means the IDFA will not be available. Later, when the user is prompted, they grant permission to tracking, which makes the IDFA now accessible. At this point, you can send an Update action, which will cause Kochava to update the IDFA associated with the kochava device ID. Any subsequent post-install events will have the updated IDFA associated with them. If you do not send an Update action in this case, subsequent post-install events will not have an IDFA associated with them.

Sample Payload:

{
    "action": "update",
    "kochava_app_id": "aaa-bbb",
    "kochava_device_id": "KA1111111702155tdbf56cde8d854c018f96e52cd8ababab",
    "data": {
      "idfa": "3ababa12-11ef-4fd3-b785-6ff1ede9d5b2"
    }

Post-Install Event Setup