## 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 Guide 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.
A standard app conversion request will contain the following parameters for App Conversion API v1.1. | 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} ``` | | `odm_info` | **Required when utilizing Integrated Conversion Measurement on iOS** *** ** * ** *** Location: Query *** ** * ** *** The value of the `info` query parameter, captured upon iOS app install or reinstall from the Google On Device Measurement (ODM): Event Data SDK. This field enables [Integrated Conversion Measurement for iOS App Campaigns.](https://support.google.com/google-ads/answer/16203286) ``` XYZr_AB8C-_zGtKjUhqtzPLeQ8lbJB5dADVR0tpZ9f-28sN5qN9GTZ_FztjL0OL FzgxUJDhZr8w6lwGxAwPcxSwR5orjWepZiVP7sRRoCiaHerR-1TP17eJKtazgeSg _CVEs13LllDTfrhVM8uWISqlg8dXobsLzmj8C7WrOlktHA5P_E23 ``` **Note**: This field needs to be cached on the app or server side so that it can be sent with the downstream conversions that happen on the app. If no value has been generated by the ODM SDK, it should be omitted. | | `id_type` | **Required** *** ** * ** *** The type of identifier passed in the `rdid` field. *** ** * ** *** #### Android ``` advertisingid ``` ``` appsetid ``` **Note** : If the `advertisingid` isn't available at the time of the conversion event, please include the `appsetid` instead. *** ** * ** *** #### iOS ``` idfa ``` ``` idfv ``` **Note** : If the `idfa` isn't available at the time of the conversion event, please include the `idfv` instead. | | `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 ``` | | `ctry_c` | **Required** *** ** * ** *** Location: Query *** ** * ** *** Two letter ISO country code to indicate the country from where the conversion originated. This field is required to enable non-user level app conversion measurement on iOS \& Android. ``` US, IN ``` | | `eea` | **Required under certain conditions** *** ** * ** *** Location: Query *** ** * ** *** The [EEA](https://www.gov.uk/eu-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](https://www.gov.uk/eu-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 microseconds precision. ``` 1432681913.123456 ``` | | `fot` | **Required** *** ** * ** *** Location: Query *** ** * ** *** The UNIX timestamp from the corresponding `first_open` in seconds with microseconds precision for all subsequent sessions and post install events. ``` 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](https://developers.google.com/adwords/api/docs/appendix/currencycodes) 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](https://developer.android.com/google/play/installreferrer/igetinstallreferrerservice). 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. ### 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](https://en.wikipedia.org/wiki/Unix_time) in seconds defined in UTC timezone with 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"]` ### Sample Requests An example of a first open request **with the On Device Measurement: Event Data SDK for Integrated Conversion Measurement** is: ``` POST /pagead/conversion/app/1.1 ?dev_token=Z_eErE4DkvcKjDM1OVE4c4 &link_id=31FF8D67E5BB5DD5029DCC2734C2F884 &app_event_type=first_open &odm_info=abcdEfadGdaf &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D &id_type=idfv &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 ×tamp=1432681913.123456 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 first open request **without the On Device Measurement: Event Data SDK for Integrated Conversion Measurement** is: ``` POST /pagead/conversion/app/1.1 ?dev_token=Z_eErE4DkvcKjDM1OVE4c4 &link_id=31FF8D67E5BB5DD5029DCC2734C2F884 &app_event_type=first_open &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D &id_type=idfv &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 ×tamp=1432681913.123456 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 post install request **with the On Device Measurement: Event Data SDK for Integrated Conversion Measurement** is: ``` POST /pagead/conversion/app/1.1 ?dev_token=Z_eErE4DkvcKjDM1OVE4c4 &link_id=31FF8D67E5BB5DD5029DCC2734C2F884 &app_event_type=first_open &odm_info=abcdEfadGdaf &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D &id_type=idfv &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 ×tamp=1432681913.123456 &&fot=1432681913.123456 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 first open request **without the On Device Measurement: Event Data SDK** is: ``` POST /pagead/conversion/app/1.1 ?dev_token=Z_eErE4DkvcKjDM1OVE4c4 &link_id=31FF8D67E5BB5DD5029DCC2734C2F884 &app_event_type=first_open &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D &id_type=idfv &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 ×tamp=1432681913.123456 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 first open request **for an Android non-deterministic conversion for ACAPI v1.1** is: ``` POST /pagead/conversion/app/1.1 ?dev_token=Z_eErE4DkvcKjDM1OVE4c4 &link_id=31FF8D67E5BB5DD5029DCC2734C2F884 &app_event_type=first_open &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D &id_type=appsetid &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 ×tamp=1432681913.123456 &ctry_c=IN Host: www.googleadservices.com User-Agent: MyAnalyticsCompany/1.0.0 (android 11; en-GB; RMX2040; Build/_; Proxy) X-Forwarded-For: 216.58.194.174 Content-Type: application/json; charset=utf-8 ``` An example of a valid conversion tracking request with a **non-custom event type** and **revenue information** is: ``` POST /pagead/conversion/app/1.1 ?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 ×tamp=1432681913.123456 &value=1.99 ¤cy_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.1 ?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 ×tamp=1432681913.123456 &value=1.99 ¤cy_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.1 ?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 ×tamp=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.1 ?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 ×tamp=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.1 ?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 ×tamp=1432681913.123456 &value=1.99 ¤cy_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 ``` > [!NOTE] > **Note:** Please review our [Privacy Compliant App Attribution Guide](https://developers.google.com/app-conversion-tracking/api/privacy-compliant-guide) for additional examples. ## Conversion Tracking Response Guide The conversion tracking response has the following format: ``` { "ad_events": [], "errors": [], "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. > [!NOTE] > `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 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 Demand_Gen 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](https://developers.google.com/adwords/api/docs/appendix/geotargeting) 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. This field is not provided for gbraid-attributed ad events that are deterministically attributed (`is_deterministic` is `true`), such as deep link attribution. ``` 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. This field is not provided for gbraid-attributed ad events that are deterministically attributed (`is_deterministic` is `true`), such as deep link attribution. ``` My App AdGroup ``` | | `asset_group_id` | Only provided when `campaign_type` is `Performance_Max`. *** ** * ** *** number *** ** * ** *** The numeric ID of the asset group that produced the ad event. This value is unique. ``` 123456789 ``` | | `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 | | `is_deterministic` | Indicates whether the attribution method is deterministic or not. *** ** * ** *** Boolean *** ** * ** *** ``` true, false ``` | | `device_model` | Device model that produced the ad event. *** ** * ** *** String *** ** * ** *** ``` sm-s936w, sm-3936w ``` | | `os_version` | The major OS version that produced the ad event. *** ** * ** *** String *** ** * ** *** ``` 14, 12 ``` | | `country` | The two-letter country code that produced the ad event. *** ** * ** *** String *** ** * ** *** ``` CA, US ``` | | `city` | The city that produced the ad event. *** ** * ** *** String *** ** * ** *** ``` san jose, london ``` | | `region` | The state or province that produced the ad event. *** ** * ** *** String *** ** * ** *** ``` california, british columbia ``` | ### Sample Responses #### An example of a response for a deterministic conversion is: ``` { "ad_events": [{ "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ", "conversion_metric": "conversion", "interaction_type": "engagement", "campaign_type": "ACI", "campaign_id": 123456789, "campaign_name": "My App Campaign", "network_type": null, "network_subtype": null, "ad_group_id": 123456789, "ad_group_name": "My App AdGroup", "asset_group_id": null, "is_deterministic": true, "timestamp": 1234567.898765 }], "errors": [], "attributed": true } ``` #### An example of a response for an iOS non-deterministic conversion is: ``` { "ad_events": [{ "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ", "conversion_metric": "conversion", "interaction_type": "engagement", "campaign_type": "ACI", "campaign_id": 123456789, "campaign_name": "My App Campaign", "network_type": null, "network_subtype": null, "ad_group_id": 123456789, "ad_group_name": "My App AdGroup", "asset_group_id": null, "is_deterministic": false, }, "device_info": { "device_model": "iphone12,3", "os_version": "14" }, "timestamp": 1432681918.123456 }], "errors": [], "attributed": true } ``` #### An example of a response for an Android non-deterministic conversion is: ``` { "ad_events": [ { "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ", "conversion_metric": "conversion", "interaction_type": "click", "campaign_type": "ACI", "campaign_id": 123456789, "campaign_name": "My App Campaign", "network_type": null, "network_subtype": null, "ad_group_id": 123456789, "ad_group_name": "My App AdGroup", "asset_group_id": null, "is_deterministic": false, "geo_info": { "city": "san jose", "country": "US", "region": "california" }, "device_info": { "device_model": "sm-s926u", "os_version": "14" }, "timestamp": 1432681918.123456 }, ], "errors": [], "warnings": [] } ``` #### An example of a response for an iOS/Android conversion attributed by gbraid 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, "interaction_type": "engagement", "network_type": null, "ad_group_id": null, "ad_group_name": null, "asset_group_id": null, "is_deterministic": true, "timestamp": 0.000000 }], "errors": [], "attributed": true, "warnings": [], } ``` #### 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": 123456789, "ad_group_name": "My App AdGroup", "asset_group_id": null, "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": null, "asset_group_id": null, "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": null, "asset_group_id": null, "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": null, "asset_group_id": null, "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": 123456789, "ad_group_name": "My App AdGroup", "asset_group_id": null, "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": 123456789, "ad_group_name": "My App AdGroup", "asset_group_id": null, "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": 123456789, "ad_group_name": "My App AdGroup", "asset_group_id": null, "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": 123456789, "ad_group_name": "My App AdGroup", "asset_group_id": null, "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": 123456789, "ad_group_name": "My App AdGroup", "asset_group_id": null, "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.1/cross_network ``` and the addition of two required parameters: | 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`. | An example of a valid cross-network attribution request is: ``` POST /pagead/conversion/app/1.1/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 ×tamp=1432681913.123456 &value=1.99 ¤cy_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.