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 vào danh sách người dùng Authorized Buyers để nhắm mục tiêu.

Dưới đây là URL API Trình tải lên hàng loạt HTTPS mẫu:

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 riêng tài khoản của bạn cho Trình tải lên hàng loạt và tính năng So khớp cookie.

Trọng tải của yêu cầu POST qua HTTPS là một vùng đệm giao thứ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. Trọng tải của mỗi yêu cầu được 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, hãy xem hướng dẫn dành cho ngôn ngữ bạn muốn sử dụng.

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

Mã nhận dạng người dùng Google
Mã 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ã 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 của 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 của Google lên danh sách người dùng.

Ví dụ: nếu bạn nhận được thông báo 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 danh sách này vào danh sách người dùng, hãy sao chép danh sách này 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ã do đối tác cung cấp là mã thuộc miền của chính đối tác. Sau đây là cách 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.
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 đặt mã nhận dạng người dùng cho miền của bạn là 123456, bạn có thể điền mã nhận dạng người 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ẻ khớp phải bao gồm phiên bản mã hoá base64 an toàn cho 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ẽ chuyển đổi 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 và thêm các 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ã 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ẽ chuyển đổi danh sách người dùng từ mã thiết bị sang mã nhận dạng người dùng của Google và thêm các mã này 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ề 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 tệp 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 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 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 POST qua HTTPS với thông báo 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 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 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, phản hồi sẽ bao gồm một UpdateUsersDataResponse với status được đặt thành BAD_COOKIE:

status: BAD_COOKIE

Ví dụ:

Đây là một tập lệnh Python mẫu 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ột danh sách người dùng bằng mã nhận dạng nhất định bằng cách 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

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ý thích 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 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 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, đố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 tuân theo các yêu cầu về sự đồng ý của người dùng cuối, đối tác phải cho biết rằng 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 mà process_consent được đặt thành false sẽ được lọc và trả về lỗi sau:

status: MISSING_CONSENT