คุณใช้ API ผู้อัปโหลดแบบกลุ่มเพื่อเพิ่มและนำรหัสโฆษณาออกจากรายการผู้ใช้ของ Authorized Buyers เพื่อกำหนดเป้าหมายได้
ต่อไปนี้คือตัวอย่าง URL ของ HTTPS สำหรับผู้อัปโหลดจำนวนมากสำหรับ 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
- รหัส Fire TV ของ Amazon
- รหัส Xbox หรือ Microsoft
อัปโหลดรหัสผู้ใช้ Google
รหัสผู้ใช้ Google คือรหัสที่เข้ารหัสจากโดเมน doubleclick.net
วิธีอัปโหลดรหัสผู้ใช้ Google มีดังนี้
- ตั้งค่าการจับคู่คุกกี้กับ Google และโฮสต์ตารางการจับคู่
- ใช้ตารางการจับคู่เพื่อแปลงรหัสผู้ใช้เป็นรหัสผู้ใช้ Google
- อัปโหลด User-ID ของ 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 ได้ด้วยการจับคู่คุกกี้ แท็กจับคู่ควรมีรหัสเวอร์ชันที่ปลอดภัยสำหรับเว็บที่เข้ารหัสฐาน 64 ซึ่งกำหนดให้กับพารามิเตอร์google_hm
เช่น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 และเพิ่มรหัสลงในรายการผู้ใช้
ขั้นตอนการทำงาน
ตัวอย่างคำขอและการตอบกลับของเครื่องมืออัปโหลดจำนวนมากทั้งหมดจะเขียนในรูปแบบข้อความ คุณจึงต้องส่งข้อความเหล่านั้นเป็นข้อความบัฟเฟอร์โปรโตคอลแบบอนุกรมไปยังปลายทาง 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.protocol มาเติมข้อมูลในรายการผู้ใช้ด้วยรหัสที่ระบุโดยใช้บริการตัวอัปโหลดจำนวนมาก
#!/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)
ขอความยินยอมในคำขออัปโหลดจำนวนมาก
พาร์ทเนอร์ที่ใช้ 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