Support Home > Server-to-Server Integration > Install Notification Setup

Install Notification Setup

Feature Summary: This document describes the recommended approach to integrate with the Kochava system to track installs resulting from the marketer’s apps user server to server APIs. Using this method helps to minimize the level of effort to integrate APIs and SDKs with your application when you want to track installs for your apps and can make for a more seamless integration.

 

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.

Kochava SDK is Not Required

Because the Kochava system does not require an SDK, you can begin sending your data to Kochava without any client side updates. Please contact your Kochava Account Management Team for information on how to get your app provisioned for tracking.

About the Kochava System

Kochava provides an open integration layer to connect with major publishers and networks so you can maximize visibility into your promotional efforts. In addition, the Kochava system provides post-back support to 3rd party networks (where applicable) so you don’t have to add additional SDK’s into your app.

Install Tracking

To track the conversions of your media efforts, Kochava must receive a single API “ping” from your servers which correspond to a unique install or startup of your application. It’s important that the API call is made at a point where the user is launching the app for the first time to maximize visibility into conversions for your campaigns. If you are interested in tracking specific post-install actions, please use the post-install event notification system to track those events post-installation.

 

NOTE: Because Kochava works across various publishers; we support all possible identifiers for devices for the purpose of reconciliation. Please note the identifier for the devices in the server-to-server API calls using the device_id_type parameter. The default for Android will be ADID and the default for iOS will be IDFA.

NOTE: With the introduction of iOS6, Apple has provided two new identifiers for advertisers and advertising publishers. To maximize reconciliation approaches, please send both IDFA and IDFV in the server-to-server call.

 

  • Identifier for Advertiser: This is a common ID across all advertisers for a given app.
  • Identifier for Vendor: This is a common ID across all apps for a given vendor.

 

Google DMA Details:

 

Consent Signals Object —

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

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

 

Parameter Details —

KeyRequiredNotes
gdpr_privacy_consentYesObject to support Google’s Consent Signals requirement.
gdpr_appliesYes/NoRequired if not passing user IP.
tc_stringYes/NoRequired if not passing ad_user_data & ad_personalization.
ad_user_dataYes/NoRequired if not passing tc_string
ad_personalizationYes/NoRequired if not passing tc_string

 

Install Example:

{
   "action":"install",
   "kochava_app_id":"koconversionsdemo777ea19bc63928c",
   "kochava_device_id":"FFFb085ab00b386",
   "data":{
      "origination_ip":"77.224.141.777",
      "device_ua":"Mozilla/5.0 (iPhone-iOS-9.3.4; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/77.0.2924.87",
      "app_version":"3.3.0",
      "gdpr_privacy_consent":{
         "gdpr_applies":1,
         "tc_string":"some example string",
         "ad_user_data":1,
         "ad_personalization":1
      },
      "device_ids":{
         "idfa":"kochava-test-idfa-2015-12-09-12",
         "idfv":"333BA75-FE08-AAA4-9EF0-98A6AD293FEC",
         "adid":"",
         "android_id":""
      }
   }
}

 

iOS14+ Install 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 below key-value pairs on all install payloads for any installs coming from OS version iOS14 or higher.

 

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

Install Event API

To send a usage event from your application, call the below server-to-server endpoint with a POST payload containing the following 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 PropertyDescription
  Required

  iOS 14+ Only

  iAd/iOS 14+ Only


kochava_app_idThis is the unique application ID used to represent the App.✔
app_versionA string representation of the application version number.
kochava_device_idkochava_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 null.✔
device_idsThis is where the relevant mobile advertising IDs will be included, most commonly IDFA, IDFV, ADID and Android ID. A custom variant may also be used, but we highly recommend working with your Kocahava CSM to leverage this capability. You must submit at least one identifier within the device_id object, and may submit more than one.✔
actionAction associated to the API event.✔
usertimeThe time the event was completed by the user in Epoch format.
origination_ipThe IP address of the device on install.✔
device_uaA string representation of the device user agent as provided by the client. This string is useful when campaigns require modeled attribution✔
dataEach event is a JSON object – see examples.✔
attBoolean indicating if iOS App Tracking Transparency was accepted or not.
att = true — Tracking is authorized
att = false — Tracking is not authorized		✔✔
att_timeThe authorization time for iOS App Tracking Transparency, must be Unix timestamp in sec.✔
att_durationThe amount of time in seconds it took the user to respond to the ATT prompt.✔
att_detailThe current ATTrackingManager.AuthorizationStatus .✔
iad-attribution✔
iad-attribution_details✔
iad-lineitem-id✔
iad-keyword✔
iad-org-name✔
iad-click-date✔
iad-adgroup-name✔
iad-campaign-id✔
iad-adgroup-id✔
iad-lineitem-name✔
iad-campaign-name✔
iad-conversion-date✔
keywordId✔
conversionType✔
creativeSetId✔
orgId✔
campaignId✔
adGroupId✔
clickDate✔
countryOrRegion✔
attribution✔

 

Sample Install Event Calls:

{
	"action": "install",
	"kochava_app_id": "koconversionsdemo777ea19bc63928c",
    "kochava_device_id":"FFFb085ab00b386",
	"data": {
		"origination_ip": "77.224.141.777",
        "device_ua":"Mozilla/5.0 (iPhone-iOS-9.3.4; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/77.0.2924.87",
"app_version": "3.3.0",
		"device_ids": {
			"idfa": "kochava-test-idfa-2015-12-09-12",
			"idfv": "333BA75-FE08-AAA4-9EF0-98A6AD293FEC",
			"adid": "",
			"android_id": ""
		}
	}
}

 

iOS14+ Sample Install Event Calls:

{
  "action": "install",
  "kochava_app_id": "koconversionsdemo777ea19bc63928c",
  "data": {
    "app_tracking_transparency": {
      "att_time": 123456789,
      "att": true,
      "att_duration": 10,
      "att_detail": "authorized"
    },
    "usertime": 1521574016,
    "origination_ip": "77.59.65.138",
    "device_ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 13_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1.2 Mobile/15E148 Safari/604.1",
    "device_ids": {
      "idfa": "{idfa}",
      "idfv": "{idfv}"
    },
    "app_version": "3.3.0"
  }
}

 

iAd/iOS14+ Sample Install Event Calls:

{
    "action": "install",
    "kochava_app_id": "koconversionsdemo777ea19bc63928c",
    "kochava_device_id": "FFFb085ab00b386",
    "data": {
      "app_tracking_transparency": {
        "att_time": 123456789,
        "att_duration": 13,
        "att": true,
        "att_detail": "authorized"
      },
      "origination_ip": "77.224.141.777",
      "usertime": 1521574016,
      "device_ver": "iPhone-iOS-14.0.0",
      "device_ids": {
        "idfa": "kochava-test-idfa-2015-12-09-12",
        "idfv": "333BA75-FE08-AAA4-9EF0-98A6AD293FEC"
      },
      "app_version": "3.3.0",
      "iad_attribution_details": {
        "Version3.1": {
          "iad-attribution": "",
          "iad-lineitem-id": "",
          "iad-keyword": "",
          "iad-org-name": "",
          "iad-click-date": "",
          "iad-adgroup-name": "",
          "iad-campaign-id": "",
          "iad-adgroup-id": "",
          "iad-lineitem-name": "",
          "iad-campaign-name": "",
          "iad-conversion-date": ""
        }
      }
    }
  }

Apple Search Ads (ASA)

Apple makes ASA attribution claims available via their Apple Ads Attribution API, which incorporates the AdServices framework. The app first makes a request for a token to the AdServices Framework, then the token can be used to request attribution results.

You can either request and only send the token to Kochava on install payloads or you can request both the token and the attribution results and forward it to Kochava. If you take the former approach, Kochava will use the token to make a server-side request to retrieve the attribution results.

The AdServices framework supports claiming attribution for devices on iOS14.3+. Claims made on devices where the user opted out of ATT will not contain a click timestamp.

NOTE: In partner reconciliation settings, Kochava allows you to configure whether or not you want to attribute claims that do not contain a timestamp, and if you choose to attribute, allows you to determine what click timestamp to manufacture based on proximity to the install timestamp.

Apple has communicated that the iAd framework will eventually be deprecated and all ASA attribution claims will need to be retrieved via the AdServices framework.

The token is created by the client, on the client and will cache for 5 minutes and be re-retrievable as needed for that duration. The attribution token is valid for 24 hours after it has been generated. If only the token is provided to Kochava on the install payload and more than 24 hours has elapsed since the generation of the token, Kochava will not be able to retrieve AdServices attribution results. If the install is sent more than 24 hours after the token is generated, it is recommended that you retrieve the attribution results using the token yourself and forward the attribution results on the install payload.

Kochava will prioritize the iAD claims when available, due to the iAd payloads containing more campaign information than the AdServices claims.

 

Sample Install Notification with iAd Attribution Results and AdServices Token:

 

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

{
  "action": "install",
  "kochava_app_id": "<guid>",
  "data": {
    "app_tracking_transparency": {
      "att_time": 123456789,
      "att": true,
      "att_duration": 10,
      "att_detail": "authorized"
    },
    "origination_ip": "77.59.65.138",
    "device_ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 13_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1.2 Mobile/15E148 Safari/604.1",
    "device_ids": {
      "idfa": "{idfa}",
      "idfv": "{idfv}"
    },
    "app_version": "3.3.0",
    "ad_services_token": "AAAAaAaAtBu0AXztoAUKbX8RxE3DEbTHLxJxqDhz+tEUtWO1TqCJ0wLUHZOS+\/aY+wThz8EBX6uv4TgET0jq4Us7AFTJ808m6QAAAVADAAAAzQAAAID9vDEyikV0wXHbnLiKRHd8zNnCWlcd9ThX2wSnA0BI5BEpRVWPJhAdzOUAxD05wx\/zm2QwEn8mtOmZYM\/6VM1VwJPnO9SgE0O6q1lLQdkfJNTFT200lf7VxBH+FNRvORzLr6iq3DkETX37K0dUVW4WeCPnUXAwcWaMpTUyEWJCogAAABrTit6bbDKmv8XYGo+J\/mLFruTrTioR7Lld+QAAAJ8BjKvP2J9bHC0AEcEIb57ujHgPyH0AAACGAwWMvmZ6dr0IkRbySz9N6oKzYFIf2VpSZAHJutgrT\/7JUNcJEtzFkfHirJP02t+qeRCytiFKoNEccCj4syU+lFPpTDnwUhd7BSnY0t0PRI2vMm74mjdOC2TAu7JOjT\/aX46PKvBI6Hr67UAdHgo67+n4oLw\/5e1udtuZkunL6UvFzQ9kQX4AAAAAAAABBEQQBwA=",
    "iad_attribution_details": {
      "Version3.1": {
        "iad-purchase-date": "2021-03-17T15:27:22Z",
        "iad-keyword": "Keyword",
        "iad-adgroup-id": "1234567890",
        "iad-creativeset-id": "1234567890",
        "iad-creativeset-name": "CreativeSetName",
        "iad-campaign-id": "1234567890",
        "iad-lineitem-id": "1234567890",
        "iad-org-id": "1234567890",
        "iad-conversion-date": "2021-03-17T15:27:22Z",
        "iad-keyword-id": "12323222",
        "iad-conversion-type": "Download",
        "iad-country-or-region": "US",
        "iad-org-name": "OrgName",
        "iad-campaign-name": "CampaignName",
        "iad-click-date": "2021-03-17T15:27:22Z",
        "iad-attribution": "true",
        "iad-adgroup-name": "AdGroupName",
        "iad-keyword-matchtype": "Broad",
        "iad-lineitem-name": "LineName"
      }
    }
  }
}

 

Sample Install Notification with iAd Attribution Results AdServices Token and Optional AdServices Attribution Results:

 

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

{
  "action": "install",
  "kochava_app_id": "<guid>",
  "data": {
    "app_tracking_transparency": {
      "att_time": 123456789,
      "att": true,
      "att_duration": 10,
      "att_detail": "authorized"
    },
    "origination_ip": "77.59.65.138",
    "device_ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 13_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1.2 Mobile/15E148 Safari/604.1",
    "device_ids": {
      "idfa": "{idfa}",
      "idfv": "{idfv}"
    },
    "app_version": "3.3.0",
    "ad_services_token": "AAAAaAaAtBu0AXztoAUKbX8RxE3DEbTHLxJxqDhz+tEUtWO1TqCJ0wLUHZOS+\/aY+wThz8EBX6uv4TgET0jq4Us7AFTJ808m6QAAAVADAAAAzQAAAID9vDEyikV0wXHbnLiKRHd8zNnCWlcd9ThX2wSnA0BI5BEpRVWPJhAdzOUAxD05wx\/zm2QwEn8mtOmZYM\/6VM1VwJPnO9SgE0O6q1lLQdkfJNTFT200lf7VxBH+FNRvORzLr6iq3DkETX37K0dUVW4WeCPnUXAwcWaMpTUyEWJCogAAABrTit6bbDKmv8XYGo+J\/mLFruTrTioR7Lld+QAAAJ8BjKvP2J9bHC0AEcEIb57ujHgPyH0AAACGAwWMvmZ6dr0IkRbySz9N6oKzYFIf2VpSZAHJutgrT\/7JUNcJEtzFkfHirJP02t+qeRCytiFKoNEccCj4syU+lFPpTDnwUhd7BSnY0t0PRI2vMm74mjdOC2TAu7JOjT\/aX46PKvBI6Hr67UAdHgo67+n4oLw\/5e1udtuZkunL6UvFzQ9kQX4AAAAAAAABBEQQBwA=",
    "iad_attribution_details": {
      "Version3.1": {
        "iad-purchase-date": "2021-03-17T15:27:22Z",
        "iad-keyword": "Keyword",
        "iad-adgroup-id": "1234567890",
        "iad-creativeset-id": "1234567890",
        "iad-creativeset-name": "CreativeSetName",
        "iad-campaign-id": "1234567890",
        "iad-lineitem-id": "1234567890",
        "iad-org-id": "1234567890",
        "iad-conversion-date": "2021-03-17T15:27:22Z",
        "iad-keyword-id": "77723222",
        "iad-conversion-type": "Download",
        "iad-country-or-region": "US",
        "iad-org-name": "OrgName",
        "iad-campaign-name": "CampaignName",
        "iad-click-date": "2021-03-17T15:27:22Z",
        "iad-attribution": "true",
        "iad-adgroup-name": "AdGroupName",
        "iad-keyword-matchtype": "Broad",
        "iad-lineitem-name": "LineName"
      }
    },
    "adservices_attribution_details": {
      "keywordId": 12323222,
      "conversionType": "Download",
      "creativeSetId": 1234567890,
      "orgId": 1234567890,
      "campaignId": 1234567890,
      "adGroupId": 1234567890,
      "clickDate": "2021-03-17T15:27Z",
      "countryOrRegion": "US",
      "attribution": true
    }
  }
}

Retrieving UTM Parameters on Facebook

In order to send the referrer data to Kochava you will need to add the below code in the data section of the request.

"data":{
     "install_referrer":{ 
          "referrer":"utm_source=apps.yourapp.com&utm_campaign=fb4a&ttt;utm_content=%7B%77app%77%3A102978293121777%2C",
          "referrer_click_time":1636415950
     }
}

Device Specific Instructions

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

DeviceSending a Usage Event Details
RokuSend GetDeviceUniqueId() as String within the UDID parameter of the S2S feed.
LGSend 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.

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

 
 

Last Modified: Oct 24, 2024 at 12:56 pm