Custom integration postback request reference

Read time 7 minutes

Review the following parameters when you send postbacks from your app's server using a custom integration to ensure your request is formatted correctly.

Required attribution postback parameters
Required attribution postback parameters

The following identification parameters must be relayed in your custom integration postback request:

ParameterDescriptionExampleNotes

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 types.
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
Required post-install event postback parameters

The following identification parameters must be relayed in your custom integration postback request for post-install event postbacks:

ParameterDescriptionExampleNotes
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.
gameId=
Unity Ads Game ID
gameId=500009999
You can retrieve your Game ID from the Apps page for the User Acquisition 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
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.

ParameterDescriptionExampleNotes
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