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

应用用户代理

作为我们打击垃圾内容的更广泛的努力的一部分，我们针对分析/广告产品代表应用用户发送了 User-Agent 标头的标准化规范。应用用户代理可以从原生代码派生，以符合以下规范：

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

这些字段的定义如下：

用户代理组件
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];
}

只有在服务器端构建应用用户代理时，才应在应用用户代理末尾添加 ; 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)

转化跟踪请求

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

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

/pagead/conversion/app/version
，其中 version 是转化跟踪 API 的预期版本。目前唯一有效的版本是 1.0。

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

转化跟踪请求
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 为 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 缺失（例如来自未征得用户同意的 ATT 用户的设备 ID），请将其设置为零。

00000000-0000-0000-0000-000000000000
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
market_referrer_gclid

在特定条件下必填

位置：查询

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

BX3QojHp4mY5MrJtFM_d1u
gclid_only_request

在特定条件下必填

位置：查询

在以下情况下，基于 gclid 的归因的标识符：rdid (adsid) 为 not 或所有 zeroes 且存在 gclid 或 market_referrer_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 标头。

示例请求

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

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

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

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=in_app_purchase
       &rdid=00000000-0000-0000-0000-000000000000
       &id_type=advertisingid
       &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
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.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 号的第 5 天的值，则发送 05。
    • 有效示例：
      • "2016-09-23"
      • "1990-12-31"

  • 时间戳

    • 时间格式：以世界协调时间 (UTC) 时区定义的 Unix/纪元时间戳，精度最高可达微秒
    • 有效示例：
      • 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

始终存在

number

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

1432681913.123456
campaign_type

始终存在

字符串

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

ACI
ACE
Search
Display
Video
Shopping
Hotel
Performance_Max
Other

ACI 是应用安装广告系列的缩写。ACE 是互动提升应用广告系列的缩写。
campaign_id

始终存在

number

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

123456789
campaign_name

始终存在

字符串

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

Occasional Gamers (Video)
ad_type

始终存在

字符串

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

应用宣传 
ClickToDownload
应用互动 
AppDeepLink
应用互动 - 安装并继续流程 
AppDeepLinkContinue
了解其他价值 
Unknown
external_customer_id

始终存在

number

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

123456789
location

始终存在

number

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

始终存在

字符串

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

Search
Display
YouTube
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
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

始终存在

number

与广告事件一起生成的广告组的数字 ID。此值必须是唯一的。

123456789
ad_group_name

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

字符串

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

My App AdGroup
creative_id

仅当 campaign_type 不是 ACI 和 ACE 时。

number

产生广告事件的广告素材广告单元的数字 ID。此值必须是唯一的。

123456789
interaction_type

此字段将始终为互动状态。

字符串

示例响应

下面举例说明了在请求包含错误时，转化跟踪响应会怎样：

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

下例展示了否定转化跟踪响应：

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

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

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

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

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

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

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

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

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

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

跨广告网络归因请求

当 Google Ads 以肯定方式响应转化跟踪请求时，API 使用方必须在识别最终点击后将跨广告网络归因决策告知 Google Ads。

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

/pagead/conversion/app/1.0/cross_network

并添加两个必需参数：

跨广告网络归因请求
ad_event_id

是否必需

位置：查询

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

是否必需

位置：查询

Google Ads 是否获得了 API 使用方的转化功劳。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 响应。