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

应用 User-Agent

为了更广泛地打击垃圾内容，我们制定了一项标准化规范，用于规范分析/广告产品代表应用用户发送的 User-Agent 标头。应用 User-Agent 可以从原生代码派生，以遵循以下规范：

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

这些字段的定义如下：

User-Agent 组件
name

分析/广告产品的名称。（Google 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 号。 （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];
}

在服务器端构建应用 User-Agent 时，仅在应用 User-Agent 的末尾包含 ; Proxy。如果应用 User-Agent 完全在客户端构建，请排除 ; 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)

转化跟踪请求指南

转化跟踪请求的目的是通知 Google Ads 某个应用事件应作为转化进行跟踪和/或用于填充再营销名单，并检索描述该事件之前发生的任何点击的元数据。

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

/pagead/conversion/app/version
，其中 version 是转化跟踪 API 的预期版本。

标准应用转化请求将包含以下参数（适用于应用转化 API v1.1）。

转化跟踪请求
dev_token

必需

位置信息：查询

向 API 使用者发放的唯一静态开发者令牌。

Z_eErE4DkvcKjDM1OVE4c4
link_id

必需

位置信息：查询

将 API 使用者的开发者令牌与特定应用相关联的链接标识符。

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 为自定义，则此字段为必填字段。

level_achieved
Level Achieved

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

可选

位置：正文

以简单的 JSON 对象形式转发任何其他富事件数据，将字符串键映射到值。可接受的值为字符串和字符串数组。

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

在 iOS 上使用集成式转化衡量时需要

位置信息：查询

在 iOS 应用从 Google 设备端衡量 (ODM) 的事件数据 SDK 安装或重新安装时捕获的 info 查询参数的值。 此字段可启用 iOS 应用广告系列的集成式转化衡量。

XYZr_AB8C-_zGtKjUhqtzPLeQ8lbJB5dADVR0tpZ9f-28sN5qN9GTZ_FztjL0OL
FzgxUJDhZr8w6lwGxAwPcxSwR5orjWepZiVP7sRRoCiaHerR-1TP17eJKtazgeSg
_CVEs13LllDTfrhVM8uWISqlg8dXobsLzmj8C7WrOlktHA5P_E23
id_type

必需

rdid 字段中传递的标识符的类型。

Android

advertisingid
 
appsetid

iOS

idfa
 
idfv
rdid

必需

位置信息：查询

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

f10e1de2-e237-4f50-b6aa-843c45cc63d6

如果缺少设备 ID（例如，来自未征得 ATT 同意的用户的设备 ID），请将其设置为全零。

00000000-0000-0000-0000-000000000000
ctry_c

必需

位置信息：查询

由两个字母组成的 ISO 国家/地区代码，用于指明转化来源的国家/地区。

此字段是必需字段，用于在 iOS 和 Android 上启用非用户级应用转化衡量。

US, IN
eea

在某些条件下为必需属性

位置信息：查询

欧洲经济区 (EEA) 范围。

0：欧洲法规不适用于相应用户和转化

1：欧洲法规适用于相应用户和转化。 例如，如果用户位于欧洲经济区 (EEA) 内，则适用欧洲相关法规。 

*Required to be sent when the value is known.
ad_personalization

在某些条件下为必需属性

位置信息：查询

个性化广告的标志

0：最终用户已拒绝同意广告个性化

1：最终用户已同意广告个性化 

*Required to be sent when the value is known.
ad_user_data

在某些条件下为必需属性

位置信息：查询

有关出于广告目的使用用户数据的同意情况标志

0：用户已拒绝出于广告目的向 Google 传输用户级数据的同意情况

1：用户已同意出于广告目的向 Google 传输用户级数据 

*Required to be sent when the value is known.
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
fot

必需

位置信息：查询

相应 first_open 中的 UNIX 时间戳（以秒为单位），精确到微秒，适用于所有后续会话和安装后事件。

1432681913.123456
value

可选

位置信息：查询

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

1.99
currency_code

在特定条件下必需

位置信息：查询

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

USD
gclid

在特定条件下必需

位置信息：查询

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

Cj0KEQjw0dy4BRCuuL_e5M
market_referrer_gclid

在特定条件下必需

位置信息：查询

通过 Play Install Referrer API 从 install_referrer 值捕获的深层链接网址中的 gclid 查询参数的值。

BX3QojHp4mY5MrJtFM_d1u
gclid_only_request

在特定条件下必需

位置信息：查询

在 rdid（advertisingid）为 not 可用或所有 zeroes 且存在 gclid 或 market_referrer_gclid 的情况下，基于 gclid 的归因的标识符。

1
gbraid

在特定条件下必需

位置信息：查询

通过打开应用的深层链接网址发送的上次查看的 gbraid 值。请注意，此值需要在应用中缓存，以便在应用中发生的未来转化中发送。

ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
app_open_source

在特定条件下必需

位置信息：查询

用于标识广告点击深层链接或自然应用会话的值。

ad_click or organic
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 标头。

事件数据编码

对于 app_event_data 正文形参，请对基本数据类型使用以下惯例：

  • Float

    • 使用点字符作为小数分隔符，不受应用本地化影响
    • 使用两位小数精度来表示货币价值。例如 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"

  • 时间戳

    • 时间格式：以秒为单位的 Unix/Epoch 时间戳，以世界协调时间 (UTC) 时区定义，精确到微秒
    • 有效示例：
      • 1478713087，适用于 2016 年 11 月 9 日星期三 17:38:07 GMT
      • 1073513982.123000 适用于 2004 年 1 月 7 日星期三 22:19:42.123 GMT

  • 数组

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

采样请求

以下是使用设备端衡量：事件数据 SDK 进行集成式转化衡量的首次打开请求示例：

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
       &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

以下是不含“设备端衡量：用于集成式转化衡量的事件数据 SDK”的首次打开请求示例：

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
       &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

以下是使用“设备端衡量：用于集成式转化衡量的事件数据”SDK 的安装后请求示例：

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
       &timestamp=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

以下是不使用 On Device Measurement: Event Data SDK 的首次打开请求示例：

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
       &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

针对 ACAPI v1.1 的 Android 非确定性转化的首次打开请求示例如下：

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
       &timestamp=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

以下是一个有效的转化跟踪请求示例，其中包含非自定义事件类型和收入信息：

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

以下是一个有效的转化跟踪请求示例，其中包含非自定义事件类型和收入信息，但不提供 rdid (advertisingid)：

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

有效的会话开始请求示例如下：

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
       &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

以下是有效会话的示例，该会话从深层链接 example://product/123?gclid=Cj0KEQjw0dy4BRCuuL_e5M 开始，并包含会话开始 重新归因请求：

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
       &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

以下是针对欧洲经济区 (EEA) 用户发出的有效转化跟踪请求示例，其中用户已同意使用广告用户数据，但拒绝了广告个性化：

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
       &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

转化跟踪响应指南

转化跟踪响应的格式如下：

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

ad_events 和 errors 数组均可能为空。

我们预计错误将是机器可读的错误代码，例如 invalid_timestamp。

错误代码

  • invalid_timestamp - 请求不包含有效的时间戳。

  • eea_missing_or_invalid - 请求未设置“eea”字段或该字段无效。

  • ad_user_data_missing - 未设置“ad_user_data”请求字段。对于所有符合 DMA 范围的请求，“ad_user_data”字段都是必需的。

  • ad_user_data_invalid -“ad_user_data”请求值无效。对于所有符合 DMA 范围的请求，“ad_user_data”字段都是必需的。

  • ad_personalization_missing_or_invalid - 请求未设置“ad_personalization”字段或该字段无效。所有在 DMA 范围内的请求都必须包含“ad_personalization”字段。

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

关于响应行为（取决于用户同意）的重要注意事项：
如果转化具有广告用户数据同意，并且用户在其 Google 用户设置中具有跨用途同意，则 Google Ads 将在所有 CPS 中响应单个最终点击。如果用户未在 Google 用户设置中同意跨产品使用同意情况，Google Ads 将根据每次点击费用 (CPS) 响应多个最终点击。

如果转化包含用户在选择的跨服务使用同意声明中同意的某些 CPS，但不包含其他 CPS，Google Ads 将针对同意跨服务使用的 CPS 返回单个最终点击，但针对未同意跨服务使用的 CPS 返回多个最终点击（按 CPS）。

转化跟踪响应
ad_event_id

始终存在

字符串

ad_event_id 用作广告事件的唯一标识符。它会在跨广告网络归因请求中重复使用，并且应记录/保留以用于调试。

Q2owS0VRancwZHk0QlJDdXVMX2U1TQ
conversion_metric

始终存在

字符串

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

conversion
timestamp

始终存在

数值

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

1432681913.123456
campaign_type

始终存在

字符串

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

ACI
ACE
ACPRE
Search
Display
Video
Shopping
Hotel
Performance_Max
Other

ACI 是“应用安装广告系列”的英文缩写。ACE 是“应用互动广告系列”的英文缩写。
campaign_id

始终存在

数值

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

123456789
campaign_name

始终存在

字符串

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

Occasional Gamers (Video)
ad_type

始终存在

字符串

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

应用宣传 
ClickToDownload
 应用互动度 
AppDeepLink
 应用互动 - 安装并继续流程 
AppDeepLinkContinue
 其他值的通用值 
Unknown
external_customer_id

始终存在

数值

生成广告事件的广告系列所属广告客户的广告客户标识符。此值可用于区分不同的 Google Ads 账号。

123456789
location

始终存在

数值

广告事件发生地理位置的位置 ID 代码。如需解读位置代码，请参阅 Google Ads API 参考文档。
network_type

始终存在

字符串

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

Search
Display
YouTube
GoogleTv
cross-network
network_subtype

当 campaign_type 为 ACI 或 ACE 且 network_type 为 Display 时，将为 null。

字符串

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

普通 Google 搜索 
GoogleSearch
 Google 搜索网络合作伙伴 
SearchPartners

显示

移动网站发布商 
mGDN
 应用发布商 
Google AdMob

YouTube

YouTube 视频广告网络 
YouTubeVideos
 YouTube 搜索广告网络 
YouTubeSearch
 视频合作伙伴 
VideoPartners

GoogleTv

GoogleTV Videos 网络 
GoogleTvVideos

跨广告网络

效果最大化广告系列跨广告资源网 
cross-network
video_id

仅当 network_type 为 YouTube 且 campaign_type 不为 ACI 和 ACE 时提供。

字符串

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

dQw4w9WgXcQ
keyword

仅当 network_type 为 Search 且 campaign_type 不为 ACI 和 ACE 时提供。

字符串

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

+food +delivery
match_type

仅当 network_type 为 Search 且 campaign_type 不为 ACI 和 ACE 时提供。

字符串

搜索关键字的匹配类型。

完全匹配 
e
 词组 
p
 广泛
b
placement

仅当 network_type 为 Display 且 campaign_type 不为 ACI 和 ACE 时提供。

字符串

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

mobileapp::1-343200656
ad_group_id

仅在 campaign_type 不为 Performance_Max 时提供。

数值

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

对于确定性归因（is_deterministic 为 true）的 gbraid 归因广告事件（例如深层链接归因），系统不会提供此字段。

123456789
ad_group_name

仅当 campaign_type 为 ACI、ACE 或 ACPRE 时提供。

字符串

产生广告事件的广告组的广告客户定义的广告组名称。此值不保证是唯一的。

对于确定性归因（is_deterministic 为 true）的 gbraid 归因广告事件（例如深层链接归因），系统不会提供此字段。

My App AdGroup
asset_group_id

仅当 campaign_type 为 Performance_Max 时提供。

数值

生成广告事件的素材资源组的数字 ID。此值是唯一的。

123456789
creative_id

仅当 campaign_type 不为 ACI、ACE、ACPRE 或 Performance_Max 时提供。

数值

生成广告事件的广告素材广告单元的数字 ID。此值保证是唯一的。

123456789
interaction_type

此字段始终为互动。

字符串
is_deterministic

指明归因方法是否是确定性的。

布尔值

true, false
device_model

生成广告事件的设备型号。

字符串

sm-s936w, sm-3936w
os_version

生成广告事件的主要操作系统版本。

字符串

14, 12
country

生成广告事件的国家/地区的双字母国家/地区代码。

字符串

CA, US
city

产生广告事件的城市。

字符串

san jose, london
region

产生广告事件的州或省/直辖市/自治区。

字符串

california, british columbia

示例响应

确定性转化的回答示例：

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

针对 iOS 非确定性转化的回答示例：

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

Android 非确定性转化的响应示例：

{
  "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": []
  }

以下是 gbraid 归因的 iOS/Android 转化响应示例：

{
  "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": [],
}

如果请求包含错误，转化跟踪响应的示例如下：

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

否定转化跟踪响应的示例如下：

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

系统会针对所有转化跟踪请求返回转化跟踪响应。

以下是针对非 EEA 用户为通用应用广告系列返回的肯定性转化跟踪响应的示例：

{
  "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": []
}

以下示例展示了针对非 EEA 用户为搜索广告系列返回的肯定性转化跟踪响应：

{
  "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": []
}

以下是针对非 EEA 用户展示广告系列的肯定性转化跟踪响应示例：

{
  "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": []
}

以下是针对 YouTube 广告系列向非 EEA 用户发送的肯定性转化跟踪响应的示例：

{
  "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": []
}
 
{
  "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
}
 
{
  "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
}
 
{
  "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
}


跨广告网络归因请求

当 Google Ads 对转化跟踪请求做出肯定响应时，API 使用者必须在确定最终点击后，将自己的跨网络归因决策通知给 Google Ads。

跨网络归因请求与原始转化跟踪请求相同，但请求路径为：

/pagead/conversion/app/1.1/cross_network

并添加了两个必需参数：

跨广告网络归因请求
ad_event_id

必需

位置信息：查询

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

必需

位置信息：查询

Google Ads 是否通过 API 消费者获得了相应转化的功劳。0 或 1。

有效的跨广告网络归因请求示例：

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
       &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 响应。