应用用户代理
我们为全方位打击垃圾内容采取了广泛的措施,其中包括针对分析/广告产品代表应用用户发送的用户代理标头制定了标准规范。应用用户代理可通过原生代码获取,以遵守以下规范:
name version (os_and_version; locale; device; build; Proxy)
这些字段的定义如下:
用户代理组件 | |
---|---|
name | 分析/广告产品的名称。( 请注意,如果用户代理在客户端上构建,则 Android 设备// Specified by API consumer. iOS 设备// Specified by API consumer. |
version | 分析/广告产品的版本。( Android 设备// Specified by API consumer. iOS 设备// Specified by API consumer. |
os_and_version | 运行该应用的操作系统及操作系统版本。( Android 设备String osAndVersion = "Android " + Build.VERSION.RELEASE; iOS 设备UIDevice *uid = [UIDevice currentDevice]; NSString *osAndVersion = [NSString stringWithFormat:@"%@ %@", [uid systemName], [uid systemVersion]]; |
locale | 设备的 IETF 语言区域标记,采用分别由两个字母组成的语言代码和国家/地区代码,两者之间用下划线分隔。( Android 设备String locale = Locale.getDefault(); iOS 设备NSString *locale = [[NSLocale currentLocale] localeIdentifier] |
device | 运行分析/广告产品的实体设备的名称。( 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/”后跟操作系统的版本号。( 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 如果要归因的是安装操作,请务必发送 |
app_event_name |
在特定情况下必需 位置:查询
level_achieved Level Achieved 该字段不得包含为 |
app_event_data |
可选 位置:正文 将任何其他丰富事件数据作为一个将字符串键映射到值的简单 JSON 对象进行转发。可接受的值是字符串和字符串数组。 {"level": 5, "attempts": 20} |
rdid |
必需 位置:查询 表示原始设备 ID 的有效 UUID 字符串。 f10e1de2-e237-4f50-b6aa-843c45cc63d6 |
id_type |
必需 位置:查询 存储在 Android 设备advertisingid iOS 设备idfa |
lat |
必需 位置:查询 设备的“限制广告跟踪”状态。
|
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,请传递与 1.9.5r6 |
timestamp |
必需 位置:查询 表示转化事件发生时间的 UNIX 时间戳(以秒为单位,精确到微秒)。 1432681913.123456 |
value |
可选 位置:查询 事件的货币价值(如果有)。应始终采用机器可读浮点值的格式,使用小数点来分隔值的整数部分和小数部分。 1.99 |
currency_code |
在特定情况下必需 位置:查询
USD |
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 ×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
{"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 ×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
针对会话的有效会话启动重新归因请求示例(该会话来自深层链接 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 ×tamp=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
表示四位数年份,例如 2016mm
表示两位数月份,例如,09 表示 9 月dd
表示两位数日期,例如,23 表示当月 23 号
- 始终发送上述指定位数的数值,例如,如果要发送表示本月 5 号的 dd 值,请发送
05
。 - 有效示例:
"2016-09-23"
"1990-12-31"
- 日期格式:yyyy-mm-dd
-
时间戳
- 时间格式:以 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 |
始终存在 字符串
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 |
如果 字符串 此字段将标识发生广告事件的 AdWords 广告网络的“子类型”。可能的值因主要广告网络类型而异。 搜索网络普通 Google 搜索GoogleSearchGoogle 搜索网络合作伙伴 SearchPartners 展示广告网络移动网站发布商mGDN应用发布商 AdMob YouTubeYouTube 视频网络YouTubeVideosYouTube 搜索网络 YouTubeSearch视频合作伙伴 VideoPartners |
video_id |
仅当 字符串 与广告事件关联的 YouTube 视频 ID。 dQw4w9WgXcQ |
keyword |
仅当 字符串 与广告事件关联的搜索关键字。 +food +delivery |
match_type |
仅当 字符串 搜索关键字的匹配类型。 完全匹配e词组匹配 p广泛匹配 b |
placement |
仅当 字符串 与广告事件相关联的展示位置。 mobileapp::1-343200656 |
ad_group_id |
仅当 数值 产生广告事件的广告组的数字 ID。此值保证唯一。 123456789 |
creative_id |
仅当 数值 产生广告事件的广告素材广告单元的数值型 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": 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 |
必需 位置:查询 来自与之前请求中的归因相关联的广告事件的 |
attributed |
必需 位置:查询 对于 API 使用者所完成的这次转化,功劳是否归于 AdWords。值为 |
下面显示一个有效的跨广告联盟归因请求示例:
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 ×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
有效的跨广告联盟归因请求将始终收到通用 200 响应,且无响应正文。