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. (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 AdWords 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
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
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.

Cj0KEQjw0dy4BRCuuL_e5M
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
       &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
{"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
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=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 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
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
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.

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

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.

UAC
Search
Display
Video

UAC is an abbreviation for Universal App Campaign.

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 AdWords accounts.

123456789
location

Always present


number


The location ID code for the geographical location of the ad event. Refer to the AdWords API reference to interpret location codes.

network_type

Always present


string


This field will identify the AdWords advertising network the ad event occurred on. The possible values are as follows.

Search
Display
YouTube
network_subtype

Will be null when campaign_type is UAC and network_type is Display.


string


This field will identify the “subtype” of the AdWords 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
AdMob

YouTube

YouTube Videos network
YouTubeVideos
YouTube Search network
YouTubeSearch
Video Partners
VideoPartners
video_id

Only provided when network_type is YouTube and campaign_type is not UAC.


string


The YouTube video ID associated with the ad event.

dQw4w9WgXcQ
keyword

Only provided when network_type is Search and campaign_type is not UAC.


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 UAC.


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 UAC.


string


The placement associated with the ad event.

mobileapp::1-343200656
ad_group_id

Only provided when campaign_type is not UAC.


number


The numeric ID of the ad group that produced with the ad event. This value is guaranteed unique.

123456789
creative_id

Only provided when campaign_type is not UAC.


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 null.


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 Universal App Campaign is:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": null,
    "campaign_type": "UAC",
    "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,
    "creative_id": null,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true
}

An example of an affirmative conversion tracking response for a Search campaign is:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": null,
    "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,
    "creative_id": 123456789,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true
}

An example of an affirmative conversion tracking response for a Display campaign is:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": null,
    "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,
    "creative_id": 123456789,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true
}

An example of an affirmative conversion tracking response for a YouTube campaign is:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": null,
    "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,
    "creative_id": 123456789,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true
}

Cross-network Attribution Request

When AdWords responds to a conversion tracking request affirmatively, the API consumer must notify AdWords 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
ad_event_id

Required


Location: Query


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

attributed

Required


Location: Query


Whether or not AdWords 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.

Send feedback about...

Mobile Apps Conversion Tracking and Remarketing
Mobile Apps Conversion Tracking and Remarketing