将广告 ID 上传到用户名单

您可以使用 Bulk Uploader API 向 Authorized Buyers 添加和移除广告 ID 用户名单进行定位

以下是 HTTPS Bulk Uploader API 网址示例：

https://cm.g.doubleclick.net/upload?nid={GoogleNetworkId}

端点接受 HTTPS POST 请求。

GoogleNetworkId 的值应为您的 Cookie 匹配网络 ID (NID) 这能唯一标识批量上传程序的账号 Cookie 匹配。

HTTPS POST 请求的负载是 协议缓冲区，用于描述要修改的列表。 有关批量上传程序服务的架构，请参见 cookie-bulk-upload-proto.txt.每个 Pod 的载荷 请求大小上限为 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 的方法如下：

  1. 通过 Google 设置 Cookie 匹配，并托管 匹配表。
  2. 使用匹配表将用户 ID 转换为 Google 用户 ID。
  3. 将 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：

  1. 设置 Google Cookie 匹配功能，并允许 让 Google 托管您的匹配表。

  2. 将合作伙伴提供的 ID 上传到用户列表。

    例如，如果您将网域的用户 ID 设为 123456，则可以 通过 Cookie 匹配将其填充到 Google 的托管匹配表中。好感度预测 代码应包含一个 base64 编码的 分配给 google_hm 参数的 ID，例如：

    https://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=MTIzNDU2&google_cm

  3. 然后，您可以将合作伙伴提供的 ID 上传到 UpdateUsersDataRequest:

    ops {
 user_id: "123456"
 user_list_id: 123
 delete: false
 user_id_type: PARTNER_PROVIDED_ID
}

  4. 然后，Google 会将用户列表从合作伙伴提供的 ID 转换为 Google User-ID，并将这些 ID 添加到您的用户列表中。

上传 IDFA 或 Android 广告 ID

您还可以上传设备 ID。

  1. 使用 UpdateUsersDataRequest 上传设备 ID：

    ops {
 user_id: "2024D65F-EBBD-11FF-23AB-823FC255913A"
 user_list_id: 111
 delete: false
 user_id_type: IDFA
}

  2. 然后，Google 会将用户列表从设备 ID 转换为 Google 用户 ID，并且 将 ID 添加到您的用户列表中。

。

工作流程

所有的批量上传程序请求和响应示例都是以文本 格式。您必须发送 将它们作为序列化 Protocol Buffer 消息发送到批量 Uploader 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

然后，发送带有序列化 UpdateUsersDataRequest 的 HTTPS POST 请求 消息作为载荷。

如果所有操作都成功执行，您将获得以下结果 UpdateUsersDataResponse:

status: NO_ERROR

如果某些操作成功了，响应会包含 UpdateUsersDataResponse，每个失败的操作都有一个错误：

status: PARTIAL_SUCCESS
errors {
  user_id: "1234567"
  error_code: UNKNOWN_ID
  user_id_type: PARTNER_PROVIDED_ID
}

如果所有操作均未成功，响应将包含 status 设置为 BAD_COOKIE 的 UpdateUsersDataResponse：

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 的合作伙伴必须表明其拥有适当的 出于使用批量上传目的与 Google 分享用户数据的法律依据 process_consent 参数。此要求适用于所有批量上传 请求。

适用于需要按照 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