App Conversion Tracking and Remarketing - Request/Response Specifications

App User-Agent

As part of our broader efforts to combat spam, we have developed a standardized specification for the User-Agent header sent by an analytics/ads product on behalf of an app user. The app User-Agent can be derived from native code to adhere to the following specification:

name version (os_and_version; locale; device; build; Proxy)

The definition of these fields is as follows:

User-Agent components
`name`	The name of the analytics/ads product. (`Google AdMob`) Note that if user agent is constructed on the client side, `name` should be the bundle ID of client app instead. Android // Specified by API consumer. iOS // Specified by API consumer.
`version`	The version of the analytics/ads product. (`7.10.1`) Android // Specified by API consumer. iOS // Specified by API consumer.
`os_and_version`	The operating system and operating system version the app is running on. (`Android 6.0` ) Android String osAndVersion = "Android " + Build.VERSION.RELEASE; iOS UIDevice uid = [UIDevice currentDevice]; NSString osAndVersion = [NSString stringWithFormat:@"%@ %@", [uid systemName], [uid systemVersion]];
`locale`	An IETF locale tag for the device, using two-letter language and country code separated by an underscore. (`en_US`) Android String locale = Locale.getDefault(); iOS NSString *locale = [[NSLocale currentLocale] localeIdentifier]
`device`	The name of the physical device running the analytics/ads product. (`iPhone9,1`) Android String device = Build.MODEL; iOS @import Darwin.sys.sysctl; NSString device(void) { size_t bufferSize = 64; NSMutableData buffer = [[NSMutableData alloc] initWithLength:bufferSize]; int status = sysctlbyname("hw.machine", buffer.mutableBytes, &bufferSize, NULL, 0); if (status != 0) { return nil; } return [[NSString alloc] initWithCString:buffer.mutableBytes encoding:NSUTF8StringEncoding]; }
`build`	"Build/" followed by the build number of the operating system. (`Build/13D15`) Android String build = "Build/" + Build.ID; iOS @import Darwin.sys.sysctl; NSString build(void) { size_t bufferSize = 64; NSMutableData buffer = [[NSMutableData alloc] initWithLength:bufferSize]; int status = sysctlbyname("kern.osversion", buffer.mutableBytes, &bufferSize, NULL, 0); if (status != 0) { return nil; } return [[NSString alloc] initWithCString:buffer.mutableBytes encoding:NSUTF8StringEncoding]; }

Only include ; Proxy at the end of the app User-Agent when constructing the app User-Agent server side. If the app User-Agent is entirely constructed on the client side, exclude ; Proxy. Thus an app User-Agent might be:

Android: AdMob/7.10.1 (Android 6.0; en_US; SM-G900F; Build/MMB29M; Proxy)
iOS: AdMob/7.10.1 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)

Conversion Tracking Request

The purpose of conversion tracking requests is to notify Google Ads of an app event that should be tracked as a conversion and/or used to populate a remarketing list, and to retrieve metadata describing any click that preceded the event.

All API calls are made to the www.googleadservices.com domain. Conversion requests are POST requests via HTTPS on the following path:

/pagead/conversion/app/version

where version is the intended version of the conversion tracking API. Currently the only valid version is 1.0.

A standard app conversion request will contain the following parameters.

Conversion Tracking Request
`dev_token`	Required Location: Query The unique, static developer token issued to the API consumer. Z_eErE4DkvcKjDM1OVE4c4
`link_id`	Required Location: Query The link identifier binding the developer token of the API consumer to a specific app. 31FF8D67E5BB5DD5029DCC2734C2F884
`app_event_type`	Required Location: Query The name of the app event that occurred. This field is an enumeration, and will only accept the following values: • first_open • session_start • in_app_purchase • view_item_list • view_item • view_search_results • add_to_cart • ecommerce_purchase • custom The `first_open` event should always be sent for attributing installs and the `session_start` event should always be sent for reattributing sessions. Use `in_app_purchase` for purchases made through the native app store; use `ecommerce_purchase` for all other purchases.
`app_event_name`	Required under certain conditions Location: Query The name of any custom app event which is not accepted in the `app_event_type` field. This field should contain 1 to 64 Unicode characters (using UTF-8 encoding). This field is required if `app_event_type` is custom. level_achieved Level Achieved This field must not contain any of the values reserved for `app_event_type`. If a reserved event name is used, the API will return an `APP_EVENT_NAME_RESERVED_VALUE` error.
`app_event_data`	Optional Location: Body Forward any additional rich event data as a simple JSON object mapping string keys to values. Acceptable values are strings and arrays of strings. {"level": 5, "attempts": 20}
`rdid`	Required Location: Query A valid UUID string representing the raw device ID. f10e1de2-e237-4f50-b6aa-843c45cc63d6 In case that device id is missing, such as device id from an ATT unconsented user, set it as all zero. 00000000-0000-0000-0000-000000000000
`id_type`	Required Location: Query The type of identifier stored in the `rdid` field. We may accept more values here in the future, but to begin with, we will support the following. Android advertisingid iOS idfa
`eea`	Required under certain conditions Location: Query The EEA scope. 0: European regulations do not apply to this user and conversion 1: European regulations apply to this user and conversion. For example, if a user is located within the EEA, they are within scope for applicable European regulations. *Required to be sent when the value is known.
`ad_personalization`	Required under certain conditions Location: Query The flags for personalized ads 0: End user has denied ads personalization consent 1: End user has granted ads personalization consent *Required to be sent when the value is known.
`ad_user_data`	Required under certain conditions Location: Query The consent flag for use of user data for ads purposes 0: User has denied consent for transmission of user level data to Google for ads purposes 1: User has granted consent for transmission of user level data to Google for ads purposes *Required to be sent when the value is known.
`lat`	Required Location: Query Limit-ad-tracking status for the device. `0`: User has not chosen to limit ad tracking. `1`: User has chosen to limit ad tracking.
`app_version`	Required Location: Query The current version of the app. This should be standardized as follows. Android packageManager.getPackageInfo(packageName(), PackageManager.GET_META_DATA).versionName iOS [[[NSBundle mainBundle] infoDictionary] objectForKey:@"CFBundleShortVersionString"] 1.2.4
`os_version`	Required Location: Query The current version of the app’s host OS. This should be standardized as follows. Android android.os.Build.VERSION.RELEASE iOS [[UIDevice currentDevice] systemVersion]
`sdk_version`	Required Location: Query The version of the SDK that measured the event. Because this is mainly used for debugging, it should reflect the release version exactly as it is published with your SDK releases. If the app does not use an SDK, please pass the same value as `app_version`. 1.9.5r6
`timestamp`	Required Location: Query The UNIX timestamp the conversion event occurred, in seconds with up to microseconds precision. 1432681913.123456
`value`	Optional Location: Query The monetary value of the event, if any. This should always be formatted as a machine-readable floating point value using a decimal point to separate the integer and fractional part of the value. 1.99
`currency_code`	Required under certain conditions Location: Query The ISO 4217 currency code for the `value` parameter. This field is required if the `value` parameter is provided and not blank. USD
`gclid`	Required under certain conditions Location: Query The value of the `gclid` query parameter from a deep link URL that opened the app. This field is required when `app_event_type` is `session_start` and the session was started from a deep link with a `gclid` query parameter. Otherwise, it should be omitted. Note: When rdid (advertisingid) is not available, gclid needs to be cached on the app or server side so that it can be sent with the future conversions that happen on the app (in addition to session_start). `gclid` is case sensitive and should not be converted to upper/lower case in the request. Cj0KEQjw0dy4BRCuuL_e5M
`market_referrer_gclid`	Required under certain conditions Location: Query The value of the `gclid` query parameter from a deep link URL captured from the install_referrer value via the Play Install Referrer API. Note that this needs to be cached on the app or server side so that it can be sent with the future conversions that happen on the app. Otherwise, it should be omitted. `gclid` is case sensitive and should not be converted to upper/lower case in the request. BX3QojHp4mY5MrJtFM_d1u
`gclid_only_request`	Required under certain conditions Location: Query Identifier for `gclid` based attribution in scenarios where rdid (advertisingid) is `not` available or all `zeroes` AND either `gclid` or `market_referrer_gclid` is present. Required to be set to `1`(true) when rdid (advertisingid) is not available. Other device id based fields such as id_type and lat should be passed as it is and not be skipped for `gclid_only_request`. 1
`gbraid`	Required under certain conditions Location: Query Last seen `gbraid` value sent through deep link URL that opened the app. Note that this needs to be cached on the app so that it can be sent with the future conversions that happen on the app. This field is required to enable non-user level app conversion measurement on iOS & Android. `gbraid` is case sensitive and should not be converted to upper/lower case in the request. ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
`app_open_source`	Required under certain conditions Location: Query Value to identify ad click deeplink or organic app sessions. Required to be sent with session start events only and need to be set to `"ad_click"` when a session_start event is driven by a deeplink containing gbraid, or set to `"organic"` when a session_start event is driven organically. Otherwise, this field should be omitted. ad_click or organic
`User-Agent`	Required Location: Header The app user agent as defined previous section. AdMob/7.10.1 (Android 6.0; en_US; SM-G900F; Build/MMB29M)
`X-Forwarded-For`	Required Location: Header The public IPv4 or IPv6 address of the device where the event was measured. 216.58.194.174

All requests must be sent via HTTPS. Pings received via HTTP will be rejected.

Please note that if the request body is empty (in cases where no rich event data is passed in the app_event_data payload), our server requires that you explicitly set the Content-Length: 0 header on your request.

Sample Request

An example of a valid conversion tracking request with a non-custom event type and revenue information is:

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=in_app_purchase
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfa
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &value=1.99
       &currency_code=USD
       &market_referrer_gclid=BX3QojHp4mY5MrJtFM_d1u
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &gclid_only_request=0
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

{"app_event_data":{"item_id":["Crayons","Markers"]}}

An example of a valid conversion tracking request with a non-custom event type and revenue information with rdid (advertisingid) not available is:

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=in_app_purchase
       &rdid=00000000-0000-0000-0000-000000000000
       &id_type=advertisingid
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=1
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &value=1.99
       &currency_code=USD
       &market_referrer_gclid=BX3QojHp4mY5MrJtFM_d1u
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &gclid_only_request=1
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; Android,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

{"app_event_data":{"item_id":["Crayons","Markers"]}}

An example of a valid session start request is:

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=session_start
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfa
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

An example of a valid session start reattribution request for a session which began from the deep link example://product/123?gclid=Cj0KEQjw0dy4BRCuuL_e5M is:

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=session_start
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfa
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

An example of a valid conversion tracking request for an EEA user with ad user data consent granted and ads personalization declined is:

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=in_app_purchase
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfa
       &eea=1
       &ad_personalization=0
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &value=1.99
       &currency_code=USD
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

Event Data Encoding

For the app_event_data body parameter, please use the following conventions for primitive data types:

Float
- Use dot character as decimal separator independently of app localisation
- Use two-digit decimal precision to represent monetary values. e.g. 2.99
- Do not use exponential notation, e.g. 2E+9
- Do not use a comma character to separate groups of digits, e.g. 1,000,000
- Valid examples:
  - -0.5
  - 2.99
  - 1000000.123
Integer
- Only send whole integer values with no decimal digits
- Do not use a comma character to separate groups of digits, e.g. 1,000,000
- Valid examples:
  - 1000
  - -11
  - 0
Date
- Date format: yyyy-mm-dd
  - yyyy = four digit year, e.g. 2016
  - mm = two digit month, e.g. 09 for September
  - dd = two digit day, e.g. 23 for the 23rd day of the month
- Always send the number of digits specified above, e.g. if sending the value for dd for the 5th day of the month, send 05.
- Valid examples:
  - "2016-09-23"
  - "1990-12-31"
Timestamp
- Time format: Unix/Epoch timestamp defined in UTC timezone with up to microseconds precision
- Valid examples:
  - 1478713087 for Wed, 09 Nov 2016 17:38:07 GMT
  - 1073513982.123000 for Wed, 07 Jan 2004 22:19:42.123 GMT
Arrays
- Only send arrays of primitive values (strings, numbers, and booleans)
- Valid Examples:
  - [123, 456, 789]
  - ["abc"]

Conversion Tracking Response

The conversion tracking response has the following format:

{
  "ad_events": [<ad event objects>],
  "errors": [<error strings>],
  "attributed": true|false
}

Both the ad_events and errors arrays may be empty.

We expect errors will be machine readable error codes, e.g. invalid_timestamp.

Error Codes

invalid_timestamp - The request did not have a valid timestamp.
eea_missing_or_invalid - Either request did not have the "eea" field set or it was invalid.
ad_user_data_missing - The "ad_user_data" request field was not set. The "ad_user_data" field is required for all in-scope DMA requests.
ad_user_data_invalid - The "ad_user_data" request value was invalid. The "ad_user_data" field is required for all in-scope DMA requests.
ad_personalization_missing_or_invalid - Either request did not have the "ad_personalization" field set or it was invalid. The "ad_personalization" field is required for all in-scope DMA requests.

Ad events are the core objects of app attribution, and will contain the following properties.

attributed can only return true if the event is imported into the conversion tracking account for the Google Ads account that drove the interaction.

Important notes regarding response behavior dependent on user consent:
If the conversion has ads user data consent and the user has cross-use consent within their Google user settings, Google Ads will respond with a single last click across all of its CPSes. If the user has not consented to cross-use consent within their Google user settings, Google Ads will respond with multiple last clicks, on a per CPS basis.

If the conversion includes certain CPSes in the user-selected cross-use consent but not others, Google Ads will respond with a single last click across the CPSes granted cross-use consent, but with multiple last clicks, on a per CPS basis, for those CPSes not granted cross-use consent.

Conversion Tracking Response
`ad_event_id`	Always present string `ad_event_id` serves as a unique identifier for ad events. It is reused in the cross-network attribution request and should be logged/retained for debugging purposes. Q2owS0VRancwZHk0QlJDdXVMX2U1TQ
`conversion_metric`	Always present string The conversion metric used for attribution. We will initially support one conversion metric. conversion
`timestamp`	Always present number The UNIX timestamp the ad event occurred, in seconds with up to microseconds precision. This value should be used for last-click attribution. 1432681913.123456
`campaign_type`	Always present string This field will identify the type of campaign that produced the ad event. The possible values are as follows. ACI ACE ACPre Search Display Video Shopping Hotel Performance_Max Other ACI is an abbreviation for App Campaign for Install. ACE is an abbreviation for App Campaigns for Engagement.
`campaign_id`	Always present number The numeric campaign ID of the campaign that produced the ad event. This value is guaranteed unique. 123456789
`campaign_name`	Always present string The advertiser-defined campaign name of the campaign that produced the ad event. This value is not guaranteed unique. Occasional Gamers (Video)
`ad_type`	Always present string The type of ad that resulted in the ad event. This value can be used to distinguish between various types of inventory as follows. App Promotion ClickToDownload App Engagement AppDeepLink App Engagement — Install and Continue flow AppDeepLinkContinue Catch-all for other values Unknown
`external_customer_id`	Always present number The advertiser identifier for the advertiser that owns the campaign that produced the ad event. This value can be used to differentiate Google Ads accounts. 123456789
`location`	Always present number The location ID code for the geographical location of the ad event. Refer to the Google Ads API reference to interpret location codes.
`network_type`	Always present string This field will identify the Google Ads advertising network the ad event occurred on. The possible values are as follows. Search Display YouTube GoogleTv cross-network
`network_subtype`	Will be `null` when `campaign_type` is `ACI` or `ACE` and `network_type` is `Display`. string This field will identify the “subtype” of the Google Ads advertising network the ad event occurred on. The possible values vary by primary network type. Search Ordinary Google Search GoogleSearch Google Search Partners SearchPartners Display Mobile Web Publishers mGDN App Publishers Google AdMob YouTube YouTube Videos network YouTubeVideos YouTube Search network YouTubeSearch Video Partners VideoPartners GoogleTv GoogleTV Videos network GoogleTvVideos cross-network Performance Max cross network cross-network
`video_id`	Only provided when `network_type` is `YouTube` and `campaign_type` is not `ACI` and `ACE`. string The YouTube video ID associated with the ad event. dQw4w9WgXcQ
`keyword`	Only provided when `network_type` is `Search` and `campaign_type` is not `ACI` and `ACE`. string The search keyword associated with the ad event. +food +delivery
`match_type`	Only provided when `network_type` is `Search` and `campaign_type` is not `ACI` and `ACE`. string The match type for search keywords. Exact e Phrase p Broad b
`placement`	Only provided when `network_type` is `Display` and `campaign_type` is not `ACI` and `ACE`. string The placement associated with the ad event. mobileapp::1-343200656
`ad_group_id`	Only provided when `campaign_type` is not `Performance_Max`. number The numeric ID of the ad group that produced with the ad event. This value is guaranteed unique. 123456789
`ad_group_name`	Only provided when `campaign_type` is `ACI`, `ACE`, or `ACPRE`. string The advertiser-defined ad group name of the ad group that produced the ad event. This value is not guaranteed unique. My App AdGroup
`creative_id`	Only provided when `campaign_type` is not `ACI`, `ACE`, `ACPRE`, or `Performance_Max`. number The numeric ID of the creative ad unit that produced the ad event. This value is guaranteed unique. 123456789
`interaction_type`	This field will always be engagement. string

Sample Responses

An example of a conversion tracking response when the request contained errors is:

{
  "ad_events": [],
  "errors": ["INVALID_CURRENCY_CODE"],
  "attributed": false
}

An example of a negative conversion tracking response is:

{
  "ad_events": [],
  "errors": [],
  "attributed": false
}

A conversion tracking response will be returned for all conversion tracking requests.

An example of an affirmative conversion tracking response for a non-EEA user for a Universal App Campaign is:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Search",
    "network_subtype": "GoogleSearch",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": null,
    "ad_group_name": "",
    "creative_id": null,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true,
  "warnings": []
}

An example of an affirmative conversion tracking response for a non-EEA user for a Search campaign is:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "Search",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Search",
    "network_subtype": "GoogleSearch",
    "video_id": null,
    "keyword": "+space +birds",
    "match_type": "b",
    "placement": null,
    "ad_group_id": 123456789,
    "ad_group_name": "My App AdGroup",
    "creative_id": 123456789,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true,
  "warnings": []
}

An example of an affirmative conversion tracking response for a non-EEA user for a Display campaign is:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "Display",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Display",
    "network_subtype": "mGDN",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": "mobile-app::2-343200656",
    "ad_group_id": 123456789,
    "ad_group_name": "My App AdGroup",
    "creative_id": 123456789,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true,
  "warnings": []
}

An example of an affirmative conversion tracking response for a non-EEA user for a YouTube campaign is:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "Video",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "YouTube",
    "network_subtype": "YouTubeVideos",
    "video_id": "dQw4w9WgXcQ",
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": 123456789,
    "ad_group_name": "My App AdGroup",
    "creative_id": 123456789,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true,
  "warnings": []
}

An example of an attributed conversion tracking response where the conversion is attributed to both Play + Search ad interactions but 5(2)(b) + 5(2)(c) cross-use consent is denied between the Play + Search CPSs is:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "click",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Display",
    "network_subtype": "",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": null,
    "ad_group_name": "",
    "creative_id": null,
    "timestamp": 1432681913.123456
  },
  {
    "ad_event_id": "I8YUwWqxvOyqcwOcqBAkYZBMaOONSd",
    "conversion_metric": "conversion",
    "interaction_type": "click",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Search",
    "network_subtype": "",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": null,
    "ad_group_name": "",
    "creative_id": null,
    "timestamp": 1432681913.123456
  },
  ],
  "errors": [],
  "warnings": [],
  "attributed": true
}

An example of an attributed conversion tracking response where the conversion is attributed to both Play + Search ad interactions and 5(2)(b) + 5(2)(c) cross-use consent is accepted between the Play + Search CPSs is similar to today's conversion behavior:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "click",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Display",
    "network_subtype": "",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": null,
    "ad_group_name": "",
    "creative_id": null,
    "timestamp": 1432681913.123456
  },
  ],
  "errors": [],
  "warnings": [],
  "attributed": true
}

An example of an attributed conversion tracking response where the conversion is attributed to both Play, Search and YouTube ad interactions and 5(2)(b) + 5(2)(c) cross-use consent is accepted between the Play + Search CPSs but is denied to the YouTube CPS is:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "click",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Display",
    "network_subtype": "",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": null,
    "ad_group_name": "",
    "creative_id": null,
    "timestamp": 1432681913.123456
  },
  {
    "ad_event_id": "I8YUwWqxvOyqcwOcqBAkYZBMaOONSd",
    "conversion_metric": "conversion",
    "interaction_type": "click",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Youtube",
    "network_subtype": "YouTubeVideos",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": null,
    "ad_group_name": "",
    "creative_id": null,
    "timestamp": 1432681913.123456
  },
  ],
  "errors": [],
  "warnings": [],
  "attributed": true
}

Cross-network Attribution Request

When Google Ads responds to a conversion tracking request affirmatively, the API consumer must notify Google Ads of its cross-network attribution decision after identifying the last click.

The cross-network attribution request is identical to the original conversion tracking request, but with a request path of:

/pagead/conversion/app/1.0/cross_network

and the addition of two required parameters:

Cross-network Attribution Request

Cross-network Attribution Request
`ad_event_id`	Required Location: Query The `ad_event_id` identifier from the ad event associated with the attribution in the prior request. `ad_event_id` is case sensitive and should not be converted to upper/lower case in the request.
`attributed`	Required Location: Query Whether or not Google Ads received credit for the conversion by the API consumer. Either `0` or `1`.

ad_event_id

Required

Location: Query

The ad_event_id identifier from the ad event associated with the attribution in the prior request.

ad_event_id is case sensitive and should not be converted to upper/lower case in the request.

attributed

Required

Location: Query

Whether or not Google Ads received credit for the conversion by the API consumer. Either 0 or 1.

An example of a valid cross-network attribution request is:

POST /pagead/conversion/app/1.0/cross_network
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=custom
       &app_event_name=level_achieved
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfa
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &value=1.99
       &currency_code=USD
       &ad_event_id=Q2owS0VRancwZHk0QlJDdXVMX2U1TQ
       &attributed=1
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

A valid cross-network attribution request will always receive a generic 200 response with no response body.

App Conversion Tracking and Remarketing - Request/Response Specifications

App User-Agent

Android

iOS

Android

iOS

Android

iOS

Android

iOS

Android

iOS

Android

iOS

Conversion Tracking Request

Android

iOS

Android

iOS

Android

iOS

Sample Request

Event Data Encoding

Conversion Tracking Response

Search

Display

YouTube

GoogleTv

cross-network

Sample Responses

An example of a conversion tracking response when the request contained errors is:

An example of a negative conversion tracking response is:

An example of an affirmative conversion tracking response for a non-EEA user for a Universal App Campaign is:

An example of an affirmative conversion tracking response for a non-EEA user for a Search campaign is:

An example of an affirmative conversion tracking response for a non-EEA user for a Display campaign is:

An example of an affirmative conversion tracking response for a non-EEA user for a YouTube campaign is:

An example of an attributed conversion tracking response where the conversion is attributed to both Play + Search ad interactions but 5(2)(b) + 5(2)(c) cross-use consent is denied between the Play + Search CPSs is:

An example of an attributed conversion tracking response where the conversion is attributed to both Play + Search ad interactions and 5(2)(b) + 5(2)(c) cross-use consent is accepted between the Play + Search CPSs is similar to today's conversion behavior:

An example of an attributed conversion tracking response where the conversion is attributed to both Play, Search and YouTube ad interactions and 5(2)(b) + 5(2)(c) cross-use consent is accepted between the Play + Search CPSs but is denied to the YouTube CPS is:

Cross-network Attribution Request