Knowledge base

Passing post-install events to Unity

Secondary conversion endpoint integration

Event parameters help refine Unity’s machine learning algorithm and improve campaign performance. Audience Pinpointer campaigns require session event data for retention optimization campaigns, and purchase event data for revenue optimization campaigns (for more information, see the Required Audience Pinpointer event parameters section below). Implement these post-install event callbacks through your third-party attribution partner.

Required Audience Pinpointer event parameters

You must include the following components with your event query for Audience Pinpointer campaigns.

Note: All parameters are case-sensitive.

Component Parameter
Base URL https://ads-secondary-conversion.unityads.unity3d.com/v1/events
User identification Mandatory identifier:

  • gamer_id={Unity Ads gamer ID of installing user}
  • ifa={iOS identifier for advertising in iOS} (required for iOS; also accepts idfa)
  • aid={Google Play Advertising Identifier} (required for Android)
Optional identifiers:

  • android_id_md5={md5 hash of lowercase Android ID}

    • Note: Unity recommends passing ifa or aid to help diagnose potential issues with the incoming data. Passing gamer_id is required for running Audience Pinpointer campaigns, except in the case of limited tracking (LAT) users.
Ad tracking setting tracking_enabled={1|0} or tracking_limited={1|0}
Campaign ID campaign_id={Unity Ads campaign ID}
Game identification game_id={Unity Ads Game ID} (required; locate this on the main page of the advertising dashboard, listed under your game’s title)

Plus one of the following:

  • platform={ios|android}&store_id={itunes id|googleplay id}
  • platform={ios|android}&bundle_id={bundle id}
  • platform={ios|android}&project_id={Unity Project ID}
Accepted values for iOS include ios, itunes, iOS, and iTunes.

Accepted values for Android include android, google, Android, Google, gplay, and GooglePlay.
Original install timestamp install_ts={unix time in seconds or milliseconds}

Note: The same parameter and value should be passed to Unity with the install attribution postback.
Event identification Identify which event was triggered by the user:

event={event name}, where the event name is one of the following:
  • session (user started a gameplay session; required for retention optimization campaigns)
  • purchase (user purchased something via IAP) and value={amount}&currency={currency} (both required for revenue optimization campaigns. Amount must be in decimal point, for example 1.23)
  • ad_revenue (user generated ad revenue) and value={amount}&currency={currency} (both required for revenue optimization campaigns. Amount must be in decimal point, for example 1.23)
Original conversion attributed? Indicate whether the original conversion of this user has been attributed to this network or not:

was_conversion_attributed=1

Optional event parameters

Include the following optional components with your event query to help improve campaign performance.

Component Parameter
Timestamp ts={unix time in seconds or milliseconds}

When the event happened. By default, the event happened at (or near) the time it was fired to the endpoint.
Event identification If the event is not a session or purchase event:

event={event name}, where the event name is one of the following:
  • registration (user registered to the app)
  • spent_credits (user spent virtual currency to buy in-game items), along with value={how many credits} (optional) and type={what type credits} (optional)
  • invite (user invited friends to the game)
  • share (user shared the game with friends)
  • level_complete (user completed a level), along with value={level name} (optional)
  • tutorial_complete (user completed the tutorial)
  • achievement_unlocked (user unlocked an achievement)
  • custom (a custom event), along with custom_event={custom_event_name} and value={value}&type={type} (optional)
Test mode test=1

This is a test event being fired to the service. It does not count as a real event from end users.
Tracking partner tracking_partner={tracking service name or other string to identify attribution provider}
App name app_name=Game+Name
Advertiser name advertiser_name=Advertiser+Name+In+Here
Original impression timestamp impression_ts=1234567890

Formatted as a Unix timestamp.
Original click timestamp click_ts=1234567890

Formatted as a Unix timestamp.
IP address ip=123.456.78.90
Ad network ad_network=UnityAds
Country country=GB
App version app_version=1.2.3
Device type Device model string:

device_type=iPhone6,2

or

device_type=samsung+GT-S7582
OS version os_version=9.3.4
Language language=en_US or language=en

Session event example iOS

ios - https://ads-secondary-conversion.unityads.unity3d.com/v1/events?ifa=AE06DF78-CA5A-46C3-BD44-1D3B6AA4D6E9&tracking_enabled=1&campaign_id=546b9257365339e0031572bd&game_id=UNITY_ADS_GAME_ID&platform=ios&store_id=123456789&event=session&ts=1466637860812&install_ts=1466637800175&was_conversion_attributed=1&gamer_id=88b48a1c94822c47b3458da3dd7aa42e9d0138a9d7036f05986fe9f763784d6887a215b69a83ca45e7b007399db6ccef20fe910b3758dd23d1cb318029d636e76428b0296d3f046f098eea964a4a711a1ce9559bcd159de21182d9f3

Session event example android

https://ads-secondary-conversion.unityads.unity3d.com/v1/events?ifa=ae06df78-ca5a-46c3-bd44-1d3b6aa4d6e9&tracking_enabled=1&campaign_id=546b9257365339e0031572bd&game_id=UNITY_ADS_GAME_ID&platform=android&store_id=com.example.store&event=session&ts=1466637860812&install_ts=1466637800175&was_conversion_attributed=1&gamer_id=88b48a1c94822c47b3458da3dd7aa42e9d0138a9d7036f05986fe9f763784d6887a215b69a83ca45e7b007399db6ccef20fe910b3758dd23d1cb318029d636e76428b0296d3f046f098eea964a4a711a1ce9559bcd159de21182d9f3

Purchase event example iOS

https://ads-secondary-conversion.unityads.unity3d.com/v1/events?ifa=AE06DF78-CA5A-46C3-BD44-1D3B6AA4D6E9&tracking_enabled=1&campaign_id=546b9257365339e0031572bd&game_id=UNITY_ADS_GAME_ID&platform=ios&store_id=123456789&event=purchase&value=1.0&currency=USD&ts=1466637860812&install_ts=1466637800175&was_conversion_attributed=1&gamer_id=88b48a1c94822c47b3458da3dd7aa42e9d0138a9d7036f05986fe9f763784d6887a215b69a83ca45e7b007399db6ccef20fe910b3758dd23d1cb318029d636e76428b0296d3f046f098eea964a4a711a1ce9559bcd159de21182d9f3

Purchase event example android

https://ads-secondary-conversion.unityads.unity3d.com/v1/events?ifa=ae06df78-ca5a-46c3-bd44-1d3b6aa4d6e9&tracking_enabled=1&campaign_id=546b9257365339e0031572bd&game_id=UNITY_ADS_GAME_ID&platform=android&store_id=com.example.store&event=purchase&value=1.0&currency=USD&ts=1466637860812&install_ts=1466637800175&was_conversion_attributed=1&gamer_id=88b48a1c94822c47b3458da3dd7aa42e9d0138a9d7036f05986fe9f763784d6887a215b69a83ca45e7b007399db6ccef20fe910b3758dd23d1cb318029d636e76428b0296d3f046f098eea964a4a711a1ce9559bcd159de21182d9f3

SKAdNetwork postback integration for MMPs

This section describes the process Unity will use for the SKAdNetwork postback integration for Mobile Measurement Partners (MMP), if the MMP partner has registered their endpoint with us.

Upon receiving the postback from a device, this is the postback integration process for the SKAdNetwork:

  1. Unity will ensure that the signature is valid, then translate the SKAdNetwork campaign-id field back to our internal campaign id.
  2. Unity will then send a JSON document to the respective MMP in a POST HTTP request, with the fields referenced in the table below.
JSON field name Type Description
ip String The IP address of the device sending the postback. iPv4 and IPv6 addresses possible.
Example: "ip":"198.51.100.1"
version String SKAdNetwork version.
Example: "version":"2.0"
app-id Integer Target app ID
ad-network-id String Ad network ID.
Example: "ad-network-id":"1232"
campaign-id Integer SKAdNetwork campaign ID.
Example: "campaign-id":23
ad-network-campaign-id String Unity’s internal campaign ID
ad-network-campaign-name String Unity’s internal campaign name
ad-network-id String Ad network ID. Example: "ad-network-id":"1232"
ad-network-source-app-id String Unity's internal Source App ID. Only available if source-app-id is available in the original postback based on the privacy threshold.
source-app-id Integer Source App Id (publisher). This field might not be present if the privacy threshold was not met.
transaction-id String SKAdNetwork postback transaction ID
attribution-signature String Attribution signature
redownload Boolean When redownload is true, it means the user downloaded the app from the app store again.
conversion-value Integer Conversion value set in the target app. This field might not be present if the privacy threshold was not met.
timestamp String Time SKAdNetwork postback is received. 10-digit UNIX timestamp.
Example: August 4, 2020, 07:25 UTC translates to "timestamp": "1596525944"
ad-network-source-app-id String Unity’s internal Source App ID. Only available if source-app-id is available in the original postback based on the privacy threshold.

Here is an example HTTP request being sent for an MMP registered with “https://mmp.example.com/skadnetwork-postback” as their endpoint:

POST /skadnetwork-postback HTTP/1.1 
Host: mmp.example.com 
Content-Type: application/json

{
    "version":"2.0",
    "app-id": 123456789,
    "ip": "1.1.1.1",
    "ad-network-campaign-name": "skadnetwork_campaign_1",
    "ad-network-source-app-id": "h4sH3d",
    "ad-network-id": "example123.skadnetwork",
    "source-app-id": 525463029",
    "transaction-id": "868eb3d91-15f5-44ee-9267-25c7655c20b6",
    "redownload": false,
    "attribution-signature": "MDYCGQCsQ4y8d4BlYU9b8Qb9BPWPi+ixk/OiRysCGQDZZ8fpJnuqs9my8iSQVbJO/oU1AXUROYU=",
    "timestamp": "1597156649200",
    "ad-network-campaign-id": "222222",
    "conversion-value": 23,
    "campaign-id": 99
}
Still need help? Get in touch!
Last updated on 12th Apr 2021