Documentation

Support

Unity Ads User Acquisition

Campaigns

Attribution

Open User Acquisition dashboard

Unity Ads User Acquisition

Custom integration postback request reference

Send server-to-server postback requests to Unity Ads to report installs and post-install events for accurate attribution in a custom integration.
Read time 5 minutesLast updated 6 days ago
Review the following parameters to ensure you format your custom integration postback request correctly.

Required attribution postback parameters

You must relay the following identification parameters in your custom integration postback request:

Parameter

Description

Example

Notes

advertisingTrackingId
(iOS)		The Identifier for Advertising (IDFA) in uppercase form.
1A2B3C4D-5E6F-7G8H-9I10-J9K8L7M65N4P
The IDFA is compulsory for all installs. You can use the raw or hashed form of the ID.
advertisingTrackingIdMD5
(iOS)		The Identifier for Advertising (IDFA) in hashed, lowercase form.
fce1e02f2ca0498021ec67f2f22dfcea
The IDFA is compulsory for all installs. You can use the raw or hashed form of the ID.
advertisingTrackingId
(Android)		The Google Advertising ID in lowercase form.
a1b2-c3d4-e5f6-g7h8
The Advertising ID is compulsory for all installs. You can use the raw or hashed form of the ID.
advertisingTrackingIdMD5
(Android)		The Google Advertising ID in MD5 hashed, lowercase form.
6fbff11856d5f0200d473af3cabd346d
The Advertising ID is compulsory for all installs. You can use the raw or hashed form of the ID.
gamerId
The unique Unity Ads identifier that is mandatory for attributing users that have Limited Ad Tracking (LAT) on.
00000000-0000-0000-0000-000000000000
The value of the 
gamer_id
parameter should be taken from starts, views, or clicks sent for attribution. If the 
gamerID
is not formatted correctly, a 
malformed
error will appear, with response code 400: 
Malformed or missing input data
.
installTimeEpoch
Install time in seconds since epoch.
1615973128
This parameter is mandatory for some campaign goals.
rawAndroidId
The Android ID in its original lowercase form.
3f4a92b6c1d8e90f
The 
rawAndroidID
parameter isn't recommended because it's not required if the Android device has correctly integrated Google Play Services and has Google Play installed. It is, however, compulsory for all Android installs that don't have a Google Advertising ID.
androidId
The Android ID in MD5 hashed form.
4a969d593d2a3e1d602fefe8e75a4d80
This isn't recommended because it's not required if the Android device has correctly integrated Google Play Services and has Google Play installed. It is, however, compulsory for all Android installs that don't have a Google Advertising ID.
attributed
A flag indicating whether this install is attributed to Unity Ads and can be charged.
  • attributed=1
  • attributed=0
The default value (
attributed=1
) indicates that the condition is true. If the condition is false (
attributed=0
), the install is unattributed and won't be charged. Only use this parameter if you send event data for all installs, as opposed to only sending installs attributed to Unity.

Required post-install event postback parameters

Relay the following identification parameters in your custom integration postback request:

Parameter

Description

Example

Notes

gamer_id=
The Unity Ads unique Gamer ID for the installing user
gamer_id=00000000-0000-0000-0000-000000000000
  • ifa=
    (iOS)
  • idfa=
Apple advertising identifier (IDFA) for a device in uppercase form.
ifa=1A2B3C4D-5E6F-7G8H-9I10-J9K8L7M65N4P
The IDFA is compulsory for all installs. You can use the raw or hashed form of the ID.
aid=
(Android)		Google Play Advertising ID in lowercase form
aid=ae06df78-ca5a-46c3-bd44-1d3b6aa4d6e9
android_id_md5=
(Android)		MD5 hash of the Google Advertising ID in lowercase form
android_id_md5=6fbff11856d5f0200d473af3cabd346d
  • tracking_enabled=
  • tracking_limited=
A flag indicating whether the user has Limited Ad Tracking enabled
  • tracking_enabled=1
  • tracking_limited=0
campaign_id=
Unity Ads campaign identifier
campaign_id=546b9257365339e0031572bd
You can retrieve your Campaign ID from the Campaigns page of the User Acquisition dashboard.
game_id=
Unity Ads Game ID
game_id=500009999
Ensure that you retrieve your advertiser Game ID from the User Acquisition dashboard. Don't use the publisher Game ID used in SDK integration from the Monetization dashboard.
platform={ios or android}&store_id={itunes id or googleplay id}
Platform + Store ID
  • platform=ios&store_id=123456789
  • platform=android&store_id=com.example.store
You can use the following values for iOS:
  • ios
  • itunes
  • iOS
  • iTunes
platform={ios or android}&bundle_id={bundle id}
Platform + Bundle ID
platform=ios&bundle_id=com.example.myapp
You can use the following values for Android:
  • android
  • google
  • Android
  • Google
  • gplay
  • GooglePlay
platform={ios or android}&project_id={Unity Project ID}
Platform + Unity Project ID
platform=android&project_id=2ff453g1-8d49-2p06-n22f-9m833592113f2
You can retrieve your Project ID from the Settings tab of any of your Projects in the Unity Dashboard.
install_ts={unix time in seconds or milliseconds}
Original install timestamp in unix format
install_ts=1466637800175
Milliseconds are the recommended best practice for timestamps.
event=session
Session event flag indicating the user started a gameplay session
event=session
event=purchase&value{amount}&currency={currency}
Purchase event flag indicating that the user completed an in-app purchase + the transaction amount
event=purchase&value=1.0&currency=USD
The recommended best practice is to use USD for currency.
event=ad_revenue&value{amount}&currency={currency}
Ad revenue event flag indicating that the user generated ad revenue + the revenue amount
  • event=ad_revenue&value=1.23&currency=EUR
  • event=ad_revenue&revenue_usd=1.23
  • Format revenue values as a decimal. For example: 
    1.05
    .
  • If you use USD for currency, you can send 
    revenue_usd={amount}
    instead of 
    value{amount}&currency={currency}
was_conversion_attributed=
Flag indicating whether the original install was attributed to Unity
was_conversion_attributed=1
  • Use 
    1
    to indicate that the original install was attributed to Unity.
  • Use 
    0
    to indicate that the original install was unattributed (not attributed to Unity).

Optional secondary postback parameters

The following post-install event parameters are not required. Use these parameters in your GET request to retrieve additional information about your app's post-install events.

Parameter

Description

Example

Notes

ts=
Timestamp of post-install event in Unix format
ts=1466637800123
Use Unix formatting for all timestamps. The recommended best practice is milliseconds, but Unity also supports timestamps in seconds.
ip=
User's IP address
ip=123.456.78.90
ad_network=
Ad network name
ad_network=UnityAds
country=
User's ISO 3166-1 alpha-2 country code
country=US
app_version=
App version number
app_version=1.2.3
device_type=
Device model name
device_type=iPhone6,2 device_type=samsung+GT-S7582
os_version=
Device OS version
os_version=14.4.2
language=
User's ISO 639-1 language code
language=en_US
ad_format=
Type of ad shown. For example: interstitial, rewarded, playable, or banner
ad_format=interstitial
This parameter is only relevant for 
ad_revenue
events and describes the format of the ad shown. These are some of the most common ad formats:
  • interstitial
  • rewarded
  • playable
  • video banner
event=
Event name for post-install events other than 
session
, 
purchase
, or 
ad_revenue
  • event=ad_view
  • event=registration
  • event=spent_credits
  • event=invite
  • event=share
  • event=level_complete
  • event=tutorial_complete
  • event=achievement_unlocked
  • event=custom_event
Use one of the following supported event names with 
event={event name}
:
  • registration
    : The user registered to the app.
  • spent_credits
    : The user spent virtual currency to buy in-game items. You can also specify these optional 
    spent_credits
    parameters: 
    • value={how many credits}
    • type={what type credits}
  • invite
    : The user invited friends to the game.
  • share
    : The user shared the game with friends.
  • level_complete
    : The user completed a level. You can also specify this optional 
    level complete
    parameter: 
    • value={level name}
  • tutorial_complete
    : The user completed a tutorial.
  • achievement_unlocked
    : The user unlocked an achievement.
  • custom
    : A custom event occurred. You can also specify these optional 
    custom
    event parameters: 
    • custom_event={custom_event_name}
    • value={value}&type={type}
tracking_partner=
Name of the tracking service or Mobile Measurement Partner (MMP)
tracking_partner=AppsFlyer
app_name=
App name
app_name=Game+Name
advertiser_name=
Name of the advertiser
advertiser_name=Advertiser+Name+In+Here
impression_ts=
Timestamp of when the ad impression occurred in Unix format
impression_ts=1466637800123
Use Unix formatting for all timestamps. The recommended best practice is milliseconds, but Unity also supports timestamps in seconds.
click_ts=
Timestamp of when the ad click occurred in Unix format
click_ts=1466637800456
Use Unix formatting for all timestamps. The recommended best practice is milliseconds, but Unity also supports timestamps in seconds.
test=
A test postback from the server that doesn't count as a real event from end users
test=1