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 API Trình tải lên hàng loạt để thêm và xoá mã nhận dạng quảng cáo khỏi Authorized Buyers danh sách người dùng để nhắm mục tiêu.

Dưới đây là ví dụ về URL của API Trình tải lên hàng loạt HTTPS:

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

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

Giá trị cho GoogleNetworkId phải là Mã mạng so khớp cookie (NID) 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 POST qua HTTPS là một mã bộ đệm giao thức mô tả danh sách cần sửa đổi. Xem giản đồ của 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 giới hạn ở 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 thông báo, xem hướng dẫn dành cho các thông báo mà bạn muốn ngôn 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ã nhận dạng do đối tác cung cấp
Mã nhận dạng cho nhà quảng cáo (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
ID 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ột mã nhận dạng người dùng 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 của Google lên danh sách người dùng.

Ví dụ: nếu bạn nhận được ưu đãi sau đây 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 Google đã mã hoá.

Để thêm thông tin này vào một danh sách người dùng, hãy sao chép thông tin đó 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 giấy tờ tuỳ thân do đối tác cung cấp lên

Mã nhận dạng do đối tác cung cấp là các mã nhận dạng thuộc miền riêng của đối tác. Sau đây là cách thực hiện tải giấy tờ tuỳ thân 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 đặt một mã nhận dạng người dùng cho miền của mình là 123456, bạn có thể điền thông tin đó vào bảng so khớp được lưu trữ của Google bằng tính năng So khớp cookie. Độ phù hợp thẻ phải bao gồm thẻ an toàn trên web phiên bản được mã hoá base64 của mã nhận dạng được gán 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ã do đối tác cung cấp lên một 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 Google user ID và thêm ID vào danh sách người dùng của bạn.

Tải lên IDFA hoặc ID quảng cáo Android

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

Tải lên mã thiết bị có 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ã thiết bị 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.

Luồng công việc

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

Ví dụ: để tải IDFA và mã nhận dạng do đối tác cung cấp lên danh sách người dùng 123, 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 yêu cầu POST qua HTTPS bằng UpdateUsersDataRequest đã 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 kết quả như sau UpdateUsersDataResponse:

status: NO_ERROR

Nếu một số thao tác thành công, phản hồi sẽ bao gồm UpdateUsersDataResponse có một 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, phản hồi sẽ bao gồm UpdateUsersDataResponse với status được đặt thành BAD_COOKIE:

status: BAD_COOKIE

Ví dụ:

Đây là tập lệnh Python mẫu minh hoạ cách bạn có thể sử dụng thư viện được tạo bằng cookie-bulk-upload.proto để điền vào một danh sách người dùng có ID nhất định sử dụ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

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

Đối với dữ liệu người dùng cần có sự đồng ý của người dùng cuối theo yêu cầu của Liên minh Châu Âu của Google Chính sách về sự đồng ý của người dùng (xem https://www.google.com/about/company/user-consent-policy/) hoặc theo luật khác của địa phương, đối tác bắt buộc phải có sự đồng ý của người dùng cuối và thể hiện sự đồng ý đã thu thập 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 bắt buộc bằng cách đặt process_consent=True.

Các yêu cầu thiếu process_consent sẽ được lọc và trả về lỗi sau đây:

status: MISSING_CONSENT_WILL_BE_DROPPED

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

status: MISSING_CONSENT