อัปโหลดรหัสโฆษณาไปยังรายการผู้ใช้

คุณสามารถใช้ Bulk Uploader API เพื่อเพิ่มและนำรหัสโฆษณาออกจากรายการผู้ใช้ Authorized Buyers สำหรับการกำหนดเป้าหมาย

ตัวอย่าง URL ของ API สำหรับเครื่องมืออัปโหลดหลายรายการผ่าน HTTPS มีดังนี้

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

ปลายทางยอมรับคำขอ HTTPS POST

ค่าสำหรับ GoogleNetworkId ควรเป็นรหัสเครือข่ายการจับคู่คุกกี้ (NID) ซึ่งระบุบัญชีของคุณสำหรับเครื่องมืออัปโหลดหลายรายการและ การจับคู่คุกกี้โดยไม่ซ้ำกัน

เพย์โหลดของคำขอ HTTPS POST คือบัฟเฟอร์โปรโตคอลที่เข้ารหัสซึ่งอธิบายรายการที่จะแก้ไข ดูสคีมาสำหรับบริการโปรแกรมอัปโหลดหลายรายการได้ที่ cookie-bulk-upload-proto.txt เพย์โหลดของแต่ละคำขอมีขนาดได้ไม่เกิน 100 KB

ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีคอมไพล์และใช้ cookie-bulk-upload.proto เพื่อ จัดรูปแบบและแยกวิเคราะห์ข้อความได้ในบทแนะนำสำหรับภาษาที่คุณต้องการ

คุณอัปโหลดตัวระบุประเภทต่อไปนี้ได้

  • รหัสผู้ใช้ Google
  • รหัสที่พาร์ทเนอร์ระบุ
  • IDFA ใน iOS
  • รหัสโฆษณา Android
  • Roku ID
  • รหัส Amazon Fire TV
  • รหัส Xbox หรือ Microsoft

อัปโหลดรหัสผู้ใช้ Google

รหัสผู้ใช้ Google คือรหัสที่เข้ารหัสจากโดเมน doubleclick.net

วิธีอัปโหลดรหัสผู้ใช้ Google มีดังนี้

  1. ตั้งค่าการจับคู่คุกกี้กับ Google และโฮสต์ ตารางการจับคู่
  2. ใช้ตารางการจับคู่เพื่อแปลงรหัสผู้ใช้เป็นรหัสผู้ใช้ Google
  3. อัปโหลดรหัสผู้ใช้ Google ไปยังรายชื่อผู้ใช้

เช่น หากคุณได้รับข้อมูลต่อไปนี้ในระหว่างการจับคู่คุกกี้

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

พารามิเตอร์ google_gid คือรหัสผู้ใช้ Google ที่เข้ารหัส

หากต้องการเพิ่มลงในรายการผู้ใช้ ให้คัดลอกไปยังUpdateUsersDataRequestเนื้อหา

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

อัปโหลดรหัสที่พาร์ทเนอร์ระบุ

รหัสที่พาร์ทเนอร์ระบุคือรหัสภายใต้โดเมนของพาร์ทเนอร์เอง วิธีอัปโหลดบัตรประจำตัวที่พาร์ทเนอร์ระบุมีดังนี้

  1. ตั้งค่าการจับคู่คุกกี้กับ Google และอนุญาตให้ Google โฮสต์ตารางการจับคู่

  2. อัปโหลดรหัสที่พาร์ทเนอร์ระบุไปยังรายการผู้ใช้

    ตัวอย่างเช่น หากคุณมีรหัสผู้ใช้สำหรับโดเมนที่ตั้งค่าเป็น 123456 คุณจะ ป้อนรหัสดังกล่าวในตารางการจับคู่ที่ Google โฮสต์ด้วยการจับคู่คุกกี้ได้ แท็กการจับคู่ควรมีเวอร์ชัน base64 ที่เข้ารหัสซึ่งปลอดภัยสำหรับเว็บของรหัสที่กำหนดให้กับพารามิเตอร์ google_hm เช่น

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

  3. จากนั้นคุณจะอัปโหลดรหัสที่พาร์ทเนอร์ระบุไปยังกลุ่มเป้าหมายตามข้อมูลผู้ใช้ได้โดยทำดังนี้ UpdateUsersDataRequest

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

  4. จากนั้น Google จะแปลรายชื่อผู้ใช้จากรหัสที่พาร์ทเนอร์ระบุเป็นรหัสผู้ใช้ Google และเพิ่มรหัสลงในรายชื่อผู้ใช้

อัปโหลด IDFA หรือรหัสโฆษณา Android

นอกจากนี้ คุณยังอัปโหลดรหัสอุปกรณ์ได้ด้วย

  1. อัปโหลดรหัสอุปกรณ์ด้วย UpdateUsersDataRequest

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

  2. จากนั้น Google จะแปลรายชื่อผู้ใช้จากรหัสอุปกรณ์เป็นรหัสผู้ใช้ Google และ เพิ่มรหัสลงในรายชื่อผู้ใช้

ขั้นตอนการทำงาน

ตัวอย่างคำขอและการตอบกลับของเครื่องมืออัปโหลดหลายรายการพร้อมกันทั้งหมดเขียนในรูปแบบข้อความ คุณต้องส่ง ข้อความเหล่านั้นเป็นข้อความ Protocol Buffer ที่ทำให้เป็นอนุกรมไปยังปลายทาง Bulk Uploader API

เช่น หากต้องการอัปโหลด IDFA และรหัสที่พาร์ทเนอร์ระบุไปยังรายชื่อผู้ใช้ 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

จากนั้นส่งคำขอ HTTPS POST พร้อมกับข้อความ UpdateUsersDataRequest ที่ซีเรียลไลซ์เป็นเพย์โหลด

หากการดำเนินการทั้งหมดสำเร็จ คุณจะได้รับข้อมูลต่อไปนี้ UpdateUsersDataResponse

status: NO_ERROR

หากการดำเนินการบางอย่างสำเร็จ การตอบกลับจะมี UpdateUsersDataResponse พร้อมข้อผิดพลาดสำหรับการดำเนินการที่ล้มเหลวแต่ละรายการ

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

หากไม่มีการดำเนินการใดสำเร็จ การตอบกลับจะมี UpdateUsersDataResponse โดยตั้งค่า status เป็น BAD_COOKIE

status: BAD_COOKIE

ตัวอย่าง

นี่คือตัวอย่างสคริปต์ Python ที่แสดงวิธีใช้ไลบรารีที่สร้างโดย cookie-bulk-upload.proto เพื่อสร้างข้อมูลในรายการผู้ใช้ที่มีรหัสที่กำหนดโดยใช้บริการอัปโหลดหลายรายการพร้อมกัน

  #!/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 ข้อกำหนดนี้มีผลกับคำขอการอัปโหลดเป็นกลุ่มทั้งหมด

สำหรับข้อมูลผู้ใช้ที่ต้องได้รับความยินยอมจากผู้ใช้ปลายทางตามที่กำหนดไว้ในนโยบายความยินยอมของผู้ใช้ EU ของ 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