Trang này được dịch bởi Cloud Translation API.

Tải mã quảng cáo lên danh sách người dùng

Bạn có thể sử dụng Bulk Uploader API để thêm và xoá mã nhận dạng quảng cáo khỏi danh sách người dùng Authorized Buyers để nhắm mục tiêu.

Sau đây là một URL mẫu của API Tải lên hàng loạt qua HTTPS:

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

Điểm cuối này chấp nhận các yêu cầu POST qua HTTPS.

Giá trị của GoogleNetworkId phải là Mã mạng so khớp cookie (NID) của bạn. Mã này xác định duy nhất tài khoản của bạn cho Trình tải lên hàng loạt và So khớp cookie.

Tải trọng của yêu cầu HTTPS POST là một vùng đệm giao thức được mã hoá, mô tả các danh sách cần sửa đổi. Xem giản đồ cho dịch vụ Trình tải lên hàng loạt trong cookie-bulk-upload-proto.txt. Tải trọng của mỗi yêu cầu được giới hạn ở mức 100 KB.

Để tìm hiểu thêm về cách biên dịch và sử dụng cookie-bulk-upload.proto để chuyển đổi tuần tự và phân tích cú pháp các thông báo, hãy xem hướng dẫn cho ngôn ngữ bạn muốn dùng.

Bạn có thể tải các loại giá trị nhận dạng sau đây lên:

Mã nhận dạng người dùng Google
Mã do đối tác cung cấp
IDFA trên iOS
Mã nhận dạng cho quảng cáo trên Android
Mã Roku
Mã nhận dạng Amazon Fire TV
Mã nhận dạng Xbox hoặc Microsoft

Tải mã nhận dạng người dùng Google lên

Mã nhận dạng người dùng Google là mã nhận dạng được mã hoá từ miền doubleclick.net.

Sau đây là cách tải mã nhận dạng người dùng trên Google lên:

Thiết lập tính năng So khớp cookie với Google và lưu trữ bảng so khớp.
Sử dụng bảng so khớp để chuyển đổi mã nhận dạng người dùng thành Mã nhận dạng người dùng của Google.
Tải mã nhận dạng người dùng Google lên danh sách người dùng.

Ví dụ: nếu bạn nhận được thông tin sau trong quá trình So khớp cookie:

https://ad.network.com/pixel?google_gid=CAESEHIV8HXNp0pFdHgi2rElMfk&google_cver=1

Tham số google_gid là Mã nhận dạng người dùng của Google đã mã hoá.

Để thêm mã này vào danh sách người dùng, hãy sao chép mã đó vào phần nội dung UpdateUsersDataRequest:

ops {
  user_id: "CAESEHIV8HXNp0pFdHgi2rElMfk"
  user_list_id: 111
  delete: false
  user_id_type: GOOGLE_USER_ID
}

Tải mã do đối tác cung cấp lên

Mã do đối tác cung cấp là mã thuộc miền của riêng đối tác. Sau đây là cách tải mã nhận dạng do đối tác cung cấp lên:

Thiết lập tính năng So khớp cookie với Google và cho phép Google lưu trữ bảng so khớp của bạn.
Tải mã nhận dạng do đối tác cung cấp lên danh sách người dùng.

Ví dụ: nếu bạn có mã nhận dạng người dùng cho miền của mình được đặt là 123456, bạn có thể điền mã nhận dạng đó vào bảng so khớp được lưu trữ của Google bằng tính năng So khớp cookie. Thẻ so khớp của bạn phải bao gồm một phiên bản được mã hoá base64 an toàn trên web của mã nhận dạng được chỉ định cho tham số google_hm, chẳng hạn như sau:
```
https://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=MTIzNDU2&google_cm
```
Sau đó, bạn có thể tải mã nhận dạng do đối tác cung cấp lên danh sách người dùng bằng UpdateUsersDataRequest:
```
ops {
 user_id: "123456"
 user_list_id: 123
 delete: false
 user_id_type: PARTNER_PROVIDED_ID
}
```
Sau đó, Google sẽ dịch danh sách người dùng từ mã nhận dạng do đối tác cung cấp sang mã nhận dạng người dùng Google và thêm mã nhận dạng đó vào danh sách người dùng của bạn.

Tải IDFA hoặc mã nhận dạng cho quảng cáo trên Android lên

Bạn cũng có thể tải mã nhận dạng thiết bị lên.

Tải mã thiết bị lên bằng UpdateUsersDataRequest:

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

Sau đó, Google sẽ dịch danh sách người dùng từ mã nhận dạng thiết bị sang mã nhận dạng người dùng Google và thêm các mã nhận dạng đó vào danh sách người dùng của bạn.

Luồng công việc

Tất cả các ví dụ về yêu cầu và phản hồi của Trình tải lên hàng loạt đều được viết ở Định dạng văn bản. Bạn phải gửi các thông báo này dưới dạng thông báo Vùng đệm giao thức được tuần tự hoá đến điểm cuối Bulk Uploader API.

Ví dụ: để tải một IDFA và mã nhận dạng do đối tác cung cấp lên danh sách người dùng 123, hãy tạo một 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

Sau đó, hãy gửi một yêu cầu HTTPS POST có thông báo UpdateUsersDataRequest được chuyển đổi tuần tự làm tải trọng.

Nếu tất cả các thao tác đều thành công, bạn sẽ nhận được UpdateUsersDataResponse sau đây:

status: NO_ERROR

Nếu một số thao tác thành công, thì phản hồi sẽ bao gồm một UpdateUsersDataResponse có lỗi cho mỗi thao tác không thành công:

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

Nếu không có thao tác nào thành công, thì phản hồi sẽ bao gồm một UpdateUsersDataResponse có status được đặt thành BAD_COOKIE:

status: BAD_COOKIE

Ví dụ:

Đây là một ví dụ về tập lệnh Python minh hoạ cách bạn có thể sử dụng thư viện do cookie-bulk-upload.proto tạo để điền sẵn danh sách người dùng bằng một mã nhận dạng nhất định bằng dịch vụ tải lên hàng loạt:

  #!/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)

Xử lý sự đồng ý trong yêu cầu tải lên hàng loạt

Những đối tác sử dụng Bulk Upload API phải cho biết rằng họ có cơ sở pháp lý phù hợp để chia sẻ dữ liệu người dùng với Google cho mục đích Bulk Upload bằng cách sử dụng tham số process_consent. Yêu cầu này áp dụng cho tất cả các yêu cầu Tải lên hàng loạt.

Đối với dữ liệu người dùng yêu cầu sự đồng ý của người dùng cuối theo Chính sách của Google về sự đồng ý của người dùng ở Liên minh Châu Âu (xem https://www.google.com/about/company/user-consent-policy/) hoặc theo luật pháp địa phương khác, các đối tác phải có được sự đồng ý của người dùng cuối và cho biết sự đồng ý đã thu thập được bằng cách đặt process_consent=True.

Đối với dữ liệu người dùng không phải tuân thủ các yêu cầu về sự đồng ý của người dùng cuối, các đối tác phải cho biết rằng họ không cần có sự đồng ý bằng cách đặt process_consent=True.

Các yêu cầu thiếu process_consent sẽ bị lọc và trả về lỗi sau:

status: MISSING_CONSENT_WILL_BE_DROPPED

Các yêu cầu có process_consent được đặt thành false sẽ được lọc và trả về lỗi sau:

status: MISSING_CONSENT