คุณสามารถใช้ 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 มีดังนี้
- ตั้งค่าการจับคู่คุกกี้กับ Google และโฮสต์ตารางการจับคู่
- ใช้ตารางการจับคู่เพื่อแปลงรหัสผู้ใช้เป็นรหัสผู้ใช้ Google
- อัปโหลดรหัสผู้ใช้ 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
}
อัปโหลดรหัสที่พาร์ทเนอร์ระบุ
รหัสที่พาร์ทเนอร์ระบุคือรหัสที่อยู่ในโดเมนของพาร์ทเนอร์เอง วิธีอัปโหลดบัตรประจำตัวที่พาร์ทเนอร์ให้มามีดังนี้
ตั้งค่าการจับคู่คุกกี้กับ Google และอนุญาตให้ Google โฮสต์ตารางการจับคู่
อัปโหลดรหัสที่พาร์ทเนอร์ระบุลงในรายชื่อผู้ใช้
เช่น หากคุณตั้งค่ารหัสผู้ใช้สําหรับโดเมนเป็น
123456
คุณสามารถป้อนข้อมูลรหัสดังกล่าวในตารางการจับคู่ที่โฮสต์ของ Google โดยใช้การจับคู่คุกกี้ แท็กการทำงานของคีย์เวิร์ดควรมีรหัสที่กําหนดให้กับพารามิเตอร์google_hm
เวอร์ชันที่เข้ารหัสฐาน 64 ซึ่งเข้ากันได้กับเว็บ เช่นhttps://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=MTIzNDU2&google_cm
จากนั้นคุณสามารถอัปโหลดรหัสที่พาร์ทเนอร์ระบุไปยังรายชื่อผู้ใช้ได้ โดยมี
UpdateUsersDataRequest
ดังนี้ops { user_id: "123456" user_list_id: 123 delete: false user_id_type: PARTNER_PROVIDED_ID }
จากนั้น Google จะแปลงรายชื่อผู้ใช้จากรหัสที่ได้จากผู้เข้าร่วมเป็นรหัสผู้ใช้ Google และเพิ่มรหัสลงในรายชื่อผู้ใช้
อัปโหลด IDFA หรือรหัสโฆษณา Android
คุณยังอัปโหลดรหัสอุปกรณ์ได้ด้วย
อัปโหลดรหัสอุปกรณ์ที่มี
UpdateUsersDataRequest
ops { user_id: "2024D65F-EBBD-11FF-23AB-823FC255913A" user_list_id: 111 delete: false user_id_type: IDFA }
จากนั้น 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