您可以使用批量上传工具 API 向 Authorized Buyers 用户名单添加和移除广告 ID,以便进行定位。
以下是 HTTPS 批量上传工具 API 网址示例:
https://cm.g.doubleclick.net/upload?nid={GoogleNetworkId}
该端点接受 HTTPS POST 请求。
GoogleNetworkId
的值应为您的 Cookie 匹配广告联盟 ID (NID),该 ID 用于在批量上传工具和Cookie 匹配中唯一标识您的账号。
HTTPS POST 请求的载荷是一个编码的协议缓冲区,用于描述要修改的列表。如需查看批量上传工具服务的架构,请参阅 cookie-bulk-upload-proto.txt。每个请求的载荷不得超过 100 KB。
如需详细了解如何编译和使用 cookie-bulk-upload.proto
序列化和解析消息,请参阅适用于您首选语言的教程。
您可以上传以下类型的标识符:
- Google 用户 ID
- 合作伙伴提供的 ID
- iOS IDFA
- Android 广告 ID
- Roku ID
- Amazon Fire TV ID
- Xbox 或 Microsoft ID
上传 Google 用户 ID
Google 用户 ID 是来自 doubleclick.net
网域的经过加密的 ID。
如需上传 Google 用户 ID,请按以下步骤操作:
- 与 Google 设置 Cookie 匹配,并托管匹配表。
- 使用匹配表将用户 ID 转换为 Google 用户 ID。
- 将 Google 用户 ID 上传到用户列表。
例如,如果您在 Cookie 匹配期间收到以下内容:
https://ad.network.com/pixel?google_gid=CAESEHIV8HXNp0pFdHgi2rElMfk&google_cver=1
google_gid
参数是经过加密的 Google 用户 ID。
如需将其添加到用户列表,请将其复制到 UpdateUsersDataRequest
正文:
ops {
user_id: "CAESEHIV8HXNp0pFdHgi2rElMfk"
user_list_id: 111
delete: false
user_id_type: GOOGLE_USER_ID
}
上传合作伙伴提供的 ID
合作伙伴提供的 ID 是合作伙伴自己网域下的 ID。如需上传合作伙伴提供的 ID,请按以下步骤操作:
与 Google 设置 Cookie 匹配,并允许 Google 托管您的匹配表。
将合作伙伴提供的 ID 上传到用户列表。
例如,如果您将网域的用户 ID 设置为
123456
,则可以使用 Cookie 匹配功能将其填充到 Google 托管的匹配表中。匹配代码应包含分配给google_hm
参数的 ID 的可在 web 环境中安全使用的 base64 编码版本,例如:https://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=MTIzNDU2&google_cm
然后,您可以使用
UpdateUsersDataRequest
将合作伙伴提供的 ID 上传到用户列表:ops { user_id: "123456" user_list_id: 123 delete: false user_id_type: PARTNER_PROVIDED_ID }
然后,Google 会将用户名单从合作伙伴提供的 ID 转换为 Google 用户 ID,并将这些 ID 添加到您的用户名单中。
上传 IDFA 或 Android 广告 ID
您还可以上传设备 ID。
使用
UpdateUsersDataRequest
上传设备 ID:ops { user_id: "2024D65F-EBBD-11FF-23AB-823FC255913A" user_list_id: 111 delete: false user_id_type: IDFA }
然后,Google 会将用户列表从设备 ID 转换为 Google 用户 ID,并将这些 ID 添加到您的用户列表中。
工作流程
所有批量上传工具请求和响应示例均采用文本格式编写。您必须将其作为序列化 Protocol Buffer 消息发送到批量上传工具 API 端点。
例如,如需将 IDFA 和合作伙伴提供的 ID 上传到用户列表 123
,请创建 UpdateUsersDataRequest
:
ops {
user_id: "2024D65F-EBBD-11FF-23AB-823FC255913A"
user_list_id: 123
delete: false
user_id_type: IDFA
}
ops {
user_id: "1234567"
user_list_id: 123
delete: false
user_id_type: PARTNER_PROVIDED_ID
}
# See warning before use. Requires affirmative end-user consent.
process_consent: true
然后,发送一个 HTTPS POST 请求,并将序列化的 UpdateUsersDataRequest
消息作为载荷。
如果所有操作都成功完成,您将获得以下 UpdateUsersDataResponse
:
status: NO_ERROR
如果部分操作成功,响应将包含一个 UpdateUsersDataResponse
,其中包含每个失败操作的错误:
status: PARTIAL_SUCCESS
errors {
user_id: "1234567"
error_code: UNKNOWN_ID
user_id_type: PARTNER_PROVIDED_ID
}
如果所有操作均未成功,响应中将包含一个 UpdateUsersDataResponse
,其中 status
设置为 BAD_COOKIE
:
status: BAD_COOKIE
示例
以下 Python 脚本示例演示了如何使用 cookie-bulk-upload.proto 生成的库,通过批量上传工具服务向用户列表中填充给定 ID:
#!/usr/bin/python
#
# Copyright 2023 Google Inc. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""A sample demonstrating usage of the Authorized Buyers Bulk Upload service.
Successfully running this example will add the provided ID to the given user
list. To learn more about the bulk uploader service, see:
https://developers.google.com/authorized-buyers/rtb/bulk-uploader
"""
import argparse
import gen.cookie_bulk_upload_pb2
import requests
BULK_UPLOAD_ENDPOINT_TEMPLATE = 'https://cm.g.doubleclick.net/upload?nid=%s'
def main(account_nid, user_list_id, user_id, user_id_type):
# Build the bulk upload request.
update_request = gen.cookie_bulk_upload_pb2.UpdateUsersDataRequest()
update_request.send_notifications = True
ops = update_request.ops
op = ops.add()
op.user_list_id = user_list_id
op.user_id = user_id
op.user_id_type = user_id_type
user_id_type_value = gen.cookie_bulk_upload_pb2.UserIdType.Name(
user_id_type)
print(f'For NID "{account_nid}", adding user ID "{user_id}" of type '
f'"{user_id_type_value}" to user list ID "{user_list_id}"')
# Execute the bulk upload request.
response = requests.post(BULK_UPLOAD_ENDPOINT_TEMPLATE % account_nid,
data=update_request.SerializeToString())
# Parse and display the response.
update_response = gen.cookie_bulk_upload_pb2.UpdateUsersDataResponse()
update_response.ParseFromString(response.content)
print('Operation completed with the following:')
print(f'\tHTTP Status code: {response.status_code}')
status_value = gen.cookie_bulk_upload_pb2.ErrorCode.Name(
update_response.status)
print(f'\tUpdateUsersDataResponse.status: {status_value}')
print(f'\tUpdateUsersDataResponse.errors: {update_response.errors}')
print('\tUpdateUsersDataResponse.notifications: '
f'{update_response.notifications}')
n_status_value = gen.cookie_bulk_upload_pb2.NotificationStatus.Name(
update_response.notification_status)
print(f'\tUpdateUsersDataResponse.notification_status: {n_status_value}')
if __name__ == '__main__':
parser = argparse.ArgumentParser(
description=('A sample demonstrating usage of the Authorized Buyers '
'bulk uploader service.'))
parser.add_argument('-n', '--account_nid',
required=True, help='The Account NID.')
parser.add_argument('-u', '--user_id',
required=True, help='The User ID to be added.')
parser.add_argument('-l', '--user_list_id', type=int, required=True,
help='The user list that the ID is being added to.')
parser.add_argument('-t', '--user_id_type', type=int, required=True,
help=('The type of user ID being added. See '
'"UserIdType" enum for more details.'))
args = parser.parse_args()
main(args.account_nid, args.user_list_id, args.user_id, args.user_id_type)
处理批量上传请求中的意见征求
使用 Bulk Upload API 的合作伙伴必须使用 process_consent 参数表明其有适当的法律依据,可以出于批量上传目的与 Google 共享用户数据。此要求适用于所有批量上传请求。
对于需要征得最终用户同意的用户数据(根据 Google 的《欧盟地区用户意见征求政策》[请参阅 https://www.google.com/about/company/user-consent-policy/] 或其他当地法律的规定),合作伙伴必须征得最终用户同意,并通过设置 process_consent=True
指明已征得用户同意。
对于不受最终用户意见征求要求约束的用户数据,合作伙伴必须通过设置 process_consent=True
指明无需征得用户同意。
缺少 process_consent
的请求将被滤除,并返回以下错误:
status: MISSING_CONSENT_WILL_BE_DROPPED
将 process_consent
设置为 false
的请求将被过滤,并返回以下错误:
status: MISSING_CONSENT