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ã quảng cáo khỏi danh sách người dùng Authorized Buyers nhằm nhắm mục tiêu. Bạn không thể sử dụng API Trình tải lên hàng loạt của Authorized Buyers để sửa đổi danh sách đối tượng của Display & Video 360.

Dưới đây là mẫu 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ị của GoogleNetworkId phải là Mã mạng so khớp cookie (NID) giúp 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à 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 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 nhằm chuyển đổi tuần tự và phân tích cú pháp thông báo, hãy xem hướng dẫn về 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
Giấy tờ tuỳ thân do đối tác cung cấp
Mã nhận dạng cho nhà quảng cáo (IDFA) dành cho iOS
Mã nhận dạng cho quảng cáo trên Android
Mã Roku
Mã Amazon Fire TV
Mã của 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à các giá trị nhận dạng được mã hoá từ miền doubleclick.net.

Dưới đây là cách tải 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 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 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 Google đã được mã hoá.

Để thêm danh sách này vào danh sách người dùng, hãy sao chép tên này vào phần nội dung của 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

Giấy tờ tuỳ thân do đối tác cung cấp là giấy tờ tuỳ thân thuộc miền riêng của đối tác. Dưới đâ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.
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 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 sẵn mã đó vào bảng so khớp do Google lưu trữ bằng tính năng So khớp cookie. Thẻ so khớp phải bao gồm phiên bản được mã hoá base64 an toàn trên web của mã đượ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 của Google, rồi thêm mã nhận dạng đó 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 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ã thiết bị sang mã nhận dạng người dùng Google, đồng thời thêm mã nhận dạng đó vào danh sách người dùng của bạn.

Quy trình làm 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 ở dạng Định dạng văn bản. Bạn phải gửi các thông báo đó dưới dạng thông báo Vùng đệm giao thức tuần tự đến điểm cuối API Trình tải lên hàng loạt.

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, hãy tạo 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 với 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:

status: NO_ERROR

Nếu một số thao tác thành công, phản hồi sẽ bao gồm một UpdateUsersDataResponse kèm theo thông báo 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à 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 mã nhận dạng nhất định vào danh sách người dùng 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

Các đố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ý phù hợp để 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ả các yêu cầu Tải lên hàng loạt.

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

Đối với dữ liệu người dùng không tuân theo 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 không cần phải có sự đồng ý bằng cách đặt process_consent=True.

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

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