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

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

ตัวอย่าง URL ของ HTTPS Bulk Uploader API มีดังนี้

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 โดยใช้การจับคู่คุกกี้ แท็กการทำงานของคีย์เวิร์ดควรมีรหัสที่กําหนดให้กับพารามิเตอร์ google_hm เวอร์ชันที่เข้ารหัสฐาน 64 ซึ่งเข้ากันได้กับเว็บ เช่น

    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 ข้อกำหนดนี้มีผลกับคำขออัปโหลดหลายรายการพร้อมกันทั้งหมด

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