应用转化跟踪和再营销 - 请求/响应规范

应用用户代理

我们为全方位打击垃圾内容采取了广泛的措施，其中包括针对分析/广告产品代表应用用户发送的用户代理标头制定了标准规范。应用用户代理可通过原生代码获取，以遵守以下规范：

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

这些字段的定义如下：

用户代理组件
name

分析/广告产品的名称。(AdMob)

请注意，如果用户代理在客户端上构建，则 name 应该是客户端应用的软件包 ID。

Android 设备

// Specified by API consumer.
iOS 设备

// Specified by API consumer.
version

分析/广告产品的版本。(7.10.1)

Android 设备

// Specified by API consumer.
iOS 设备

// Specified by API consumer.
os_and_version

运行该应用的操作系统及操作系统版本。(Android 6.0 )

Android 设备

String osAndVersion =
    "Android " + Build.VERSION.RELEASE;
iOS 设备

UIDevice *uid =
  [UIDevice currentDevice];
NSString *osAndVersion =
  [NSString
    stringWithFormat:@"%@ %@",
    [uid systemName],
    [uid systemVersion]];
locale

设备的 IETF 语言区域标记，采用分别由两个字母组成的语言代码和国家/地区代码，两者之间用下划线分隔。(en_US)

Android 设备

String locale = Locale.getDefault();
iOS 设备

NSString *locale =
  [[NSLocale currentLocale]
    localeIdentifier]
device

运行分析/广告产品的实体设备的名称。(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/”后跟操作系统的版本号。(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];
}

仅当在服务器端构建应用用户代理时，才应在应用用户代理末尾添加 ; Proxy。如果应用用户代理完全在客户端构建，请不要添加 ; Proxy。因此，应用用户代理可以是：

  • 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)

转化跟踪请求

发送转化跟踪请求的目的是，将应作为转化加以跟踪并/或用于填充再营销列表的应用事件通知给 AdWords，以及检索用来描述该事件之前的任何点击的元数据。

所有 API 调用都会发送到 www.googleadservices.com 网域。转化请求是通过 HTTPS 按照以下路径发出的 POST 请求：

/pagead/conversion/app/version
其中“version”是希望使用的转化跟踪 API 版本。目前唯一有效的版本是 1.0。

标准应用转化请求将包含以下参数。

转化跟踪请求
dev_token

必需

位置：查询

为 API 使用者提供的唯一静态开发者令牌。


Z_eErE4DkvcKjDM1OVE4c4
link_id

必需

位置：查询

用于将 API 使用者的开发者令牌绑定到特定应用的关联 ID。


31FF8D67E5BB5DD5029DCC2734C2F884
app_event_type

必需

位置：查询

发生的应用事件的名称。此字段为枚举类型，只接受下列值：


 • first_open
 • session_start
 • in_app_purchase
 • view_item_list
 • view_item
 • view_search_results
 • add_to_cart
 • ecommerce_purchase
 • custom

如果要归因的是安装操作，请务必发送 first_open 事件；如果要对会话进行重新归因，请务必发送 session_start 事件。对于通过本机应用商店进行的购买，请使用 in_app_purchase；对于所有其他购买，请使用 ecommerce_purchase。
app_event_name

在特定情况下必需

位置：查询

app_event_type 字段中不接受的任何自定义应用事件的名称。该字段应包含 1-64 个 Unicode 字符（使用 UTF-8 编码）。如果 app_event_type 为 custom，则该字段是必需的。


level_achieved
Level Achieved

该字段不得包含为 app_event_type 预留的任何值。如果使用预留的事件名称，API 将返回 APP_EVENT_NAME_RESERVED_VALUE 错误。
app_event_data

可选

位置：正文

将任何其他丰富事件数据作为一个将字符串键映射到值的简单 JSON 对象进行转发。可接受的值是字符串和字符串数组。


{"level": 5, "attempts": 20}
rdid

必需

位置：查询

表示原始设备 ID 的有效 UUID 字符串。


f10e1de2-e237-4f50-b6aa-843c45cc63d6
id_type

必需

位置：查询

存储在 rdid 字段中的标识符的类型。我们未来可能接受更多值，不过首先将支持以下值。

Android 设备


advertisingid

iOS 设备


idfa
lat

必需

位置：查询

设备的“限制广告跟踪”状态。

  • 0：用户未选择限制广告跟踪。
  • 1：用户已选择限制广告跟踪。
app_version

必需

位置：查询

应用的当前版本。应按如下方式进行标准化。

Android 设备


packageManager.getPackageInfo(packageName(),
  PackageManager.GET_META_DATA).versionName

iOS 设备


[[[NSBundle mainBundle] infoDictionary]
  objectForKey:@"CFBundleShortVersionString"]


1.2.4
os_version

必需

位置：查询

应用的主机操作系统的当前版本。应按如下方式进行标准化。

Android 设备


android.os.Build.VERSION.RELEASE

iOS 设备


[[UIDevice currentDevice] systemVersion]
sdk_version

必需

位置：查询

衡量事件的 SDK 的版本。由于该参数主要用于调试，并且随您的 SDK 版本一起发布，因此应准确反映发布版本。如果应用未使用 SDK，请传递与 app_version 相同的值。


1.9.5r6
timestamp

必需

位置：查询

表示转化事件发生时间的 UNIX 时间戳（以秒为单位，精确到微秒）。


1432681913.123456
value

可选

位置：查询

事件的货币价值（如果有）。应始终采用机器可读浮点值的格式，使用小数点来分隔值的整数部分和小数部分。


1.99
currency_code

在特定情况下必需

位置：查询

value 参数的 ISO 4217 货币代码。如果提供了 value 参数且该参数不为空，则此字段为必需。


USD
gclid

在特定情况下必需

位置：查询

打开过应用的深层链接网址中的 gclid 查询参数值。


Cj0KEQjw0dy4BRCuuL_e5M
User-Agent

必需

位置：标头

在上一部分中定义的应用用户代理。


AdMob/7.10.1 (Android 6.0; en_US; SM-G900F; Build/MMB29M)
X-Forwarded-For

必需

位置：标头

衡量事件的设备的公开 IPv4 或 IPv6 地址。


216.58.194.174

所有请求均必须通过 HTTPS 发送。通过 HTTP 接收的 ping 会被拒绝。

请注意，如果请求正文为空（在 app_event_data 有效负荷中没有传递丰富事件数据的情况下），则我们的服务器会要求您在请求中明确设置 Content-Length: 0 标头。

请求示例

下面显示一个采用非自定义事件类型且包含收入信息的有效转化跟踪请求示例：

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"]}}

下面显示一个有效的会话启动请求示例：

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

针对会话的有效会话启动重新归因请求示例（该会话来自深层链接 example://product/123?gclid=Cj0KEQjw0dy4BRCuuL_e5M）如下：

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

事件数据编码

对于 app_event_data 正文参数，请遵循基元数据类型的以下惯例：

  • 浮点

    • 使用点字符作为小数点分隔符，而不考虑应用的本地化规则
    • 使用精确到小数点后两位的数值表示货币价值，例如 2.99
    • 请勿使用指数计数法，例如 2E+9
    • 请勿使用逗号来分隔数位组，例如 1,000,000
    • 有效示例：
      • -0.5
      • 2.99
      • 1000000.123

  • 整数

    • 仅发送没有小数位数的整数值
    • 请勿使用逗号来分隔数位组，例如 1,000,000
    • 有效示例：
      • 1000
      • -11
      • 0

  • 日期

    • 日期格式：yyyy-mm-dd
      • yyyy 表示四位数年份，例如 2016
      • mm 表示两位数月份，例如，09 表示 9 月
      • dd 表示两位数日期，例如，23 表示当月 23 号
    • 始终发送上述指定位数的数值，例如，如果要发送表示本月 5 号的 dd 值，请发送 05。
    • 有效示例：
      • "2016-09-23"
      • "1990-12-31"

  • 时间戳

    • 时间格式：以 UTC 时区定义的 Unix/Epoch 时间戳，精确到微秒
    • 有效示例：
      • 1478713087 表示 2016 年 11 月 9 日星期三 17:38:07（格林尼治标准时间）
      • 1073513982.123000 表示 2004 年 1 月 7 日星期三 22:19:42.123（格林尼治标准时间）

  • 数组

    • 仅发送基元值数组（字符串、数字和布尔值）
    • 有效示例：
      • [123, 456, 789]
      • ["abc"]

转化跟踪响应

转化跟踪响应采用以下格式：

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

表示广告事件的 ad_events 数组和表示错误的 errors 数组均可为空。

错误应采用机器可读的错误代码表示，例如 invalid_timestamp。

广告事件是应用归因的核心对象，将包含以下属性。

转化跟踪响应
ad_event_id

始终存在

字符串

ad_event_id 用作广告事件的唯一标识符。可在跨广告联盟归因请求中重复使用，并应出于调试目的予以记录/保留。


Q2owS0VRancwZHk0QlJDdXVMX2U1TQ
conversion_metric

始终存在

字符串

用于归因的转化指标。我们最初将支持一个转化指标。


conversion
timestamp

始终存在

数值

表示广告事件发生时间的 UNIX 时间戳（以秒为单位，精确到微秒）。对于最终点击归因，应采用此值。


1432681913.123456
campaign_type

始终存在

字符串

此字段将标识产生广告事件的广告系列的类型。可能的值如下。


UAC
Search
Display
Video
Shopping

UAC 是通用应用广告系列 (Universal App Campaign) 的缩写形式。
campaign_id

始终存在

数值

产生广告事件的广告系列的数值型广告系列 ID。此值保证唯一。


123456789
campaign_name

始终存在

字符串

产生广告事件的广告系列的名称（由广告客户定义）。此值不能保证唯一。


Occasional Gamers (Video)
ad_type

始终存在

字符串

产生广告事件的广告的类型。此值可用于区分各种类型的广告资源，如下所示。

应用宣传

ClickToDownload
应用互动

AppDeepLink
应用互动 - 安装和继续互动流程

AppDeepLinkContinue
其他值的综合

Unknown
external_customer_id

始终存在

数值

对于产生广告事件的广告系列，此值是指拥有该广告系列的广告客户的广告客户标识符。此值可用于区分 AdWords 帐号。


123456789
location

始终存在

数值

广告事件的地理位置的地理位置 ID 代码。请参阅 AdWords API 参考来解读地理位置代码。
network_type

始终存在

字符串

此字段将标识发生广告事件的 AdWords 广告网络。可能的值如下。


Search
Display
YouTube
network_subtype

如果 campaign_type 是 UAC 且 network_type 是 Display，则此值为 null。

字符串

此字段将标识发生广告事件的 AdWords 广告网络的“子类型”。可能的值因主要广告网络类型而异。

搜索网络

普通 Google 搜索

GoogleSearch
Google 搜索网络合作伙伴

SearchPartners

展示广告网络

移动网站发布商

mGDN
应用发布商

AdMob

YouTube

YouTube 视频网络

YouTubeVideos
YouTube 搜索网络

YouTubeSearch
视频合作伙伴

VideoPartners
video_id

仅当 network_type 是 YouTube 且 campaign_type 不是 UAC 时提供。

字符串

与广告事件关联的 YouTube 视频 ID。


dQw4w9WgXcQ
keyword

仅当 network_type 是 Search 且 campaign_type 不是 UAC 时提供。

字符串

与广告事件关联的搜索关键字。


+food +delivery
match_type

仅当 network_type 是 Search 且 campaign_type 不是 UAC 时提供。

字符串

搜索关键字的匹配类型。

完全匹配

e
词组匹配

p
广泛匹配

b
placement

仅当 network_type 是 Display 且 campaign_type 不是 UAC 时提供。

字符串

与广告事件相关联的展示位置。


mobileapp::1-343200656
ad_group_id

仅当 campaign_type 不是 UAC 时提供。

数值

产生广告事件的广告组的数字 ID。此值保证唯一。


123456789
creative_id

仅当 campaign_type 不是 UAC 时提供。

数值

产生广告事件的广告素材广告单元的数值型 ID。此值保证唯一。


123456789
interaction_type

该字段将始终为 null。

字符串

响应示例

下面显示请求包含错误时的转化跟踪响应示例：

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

下例是一个否定性的转化跟踪响应：

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

所有转化跟踪请求都会获得转化跟踪响应。

下例是针对通用应用广告系列的一个肯定性的转化跟踪响应：

{
  "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
}

下例是针对搜索广告系列的一个肯定性的转化跟踪响应：

{
  "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
}

下例是针对展示广告系列的一个肯定性的转化跟踪响应：

{
  "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
}

下例是针对 YouTube 广告系列的一个肯定性的转化跟踪响应：：

{
  "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
}

跨广告联盟归因请求

当 AdWords 以肯定的方式响应转化跟踪请求时，API 使用者必须在识别最终点击后将其跨广告联盟归因决定通知给 AdWords。

跨广告联盟归因请求与原始转化跟踪请求相同，不过前者的请求路径为：

/pagead/conversion/app/1.0/cross_network

且需添加两个必需参数：

跨广告联盟归因请求
ad_event_id

必需

位置：查询

来自与之前请求中的归因相关联的广告事件的 ad_event_id 标识符。
attributed

必需

位置：查询

对于 API 使用者所完成的这次转化，功劳是否归于 AdWords。值为 0 或 1。

下面显示一个有效的跨广告联盟归因请求示例：

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

有效的跨广告联盟归因请求将始终收到通用 200 响应，且无响应正文。