אפשר להשתמש ב-Bulk Uploader API כדי להוסיף מזהי מודעות ולהסיר מזהי מודעות מרשימות משתמשים ב-Authorized Buyers לצורך טירגוט.
דוגמה לכתובת URL של API להעלאה בכמות גדולה באמצעות HTTPS:
https://cm.g.doubleclick.net/upload?nid={GoogleNetworkId}
נקודת הקצה מקבלת בקשות HTTPS POST.
הערך של GoogleNetworkId צריך להיות מזהה הרשת להתאמת קובצי Cookie (NID)
שמזהה באופן ייחודי את החשבון שלכם בכלי להעלאה בכמות גדולה ובהתאמת קובצי Cookie.
המטען הייעודי (payload) של בקשת ה-HTTPS POST הוא מאגר פרוטוקולים מקודד שמתאר את הרשימות שצריך לשנות. אפשר לראות את הסכימה של שירות ההעלאה בכמות גדולה בקובץ cookie-bulk-upload-proto.txt. המטען הייעודי (payload) של כל בקשה מוגבל ל-100KB.
כדי לקבל מידע נוסף על קומפילציה ושימוש ב-cookie-bulk-upload.proto כדי לבצע סריאליזציה וניתוח של הודעות, אפשר לעיין במדריך לשפה המועדפת.
אפשר להעלות את סוגי המזהים הבאים:
- מזהה משתמש Google
- מזהה שסופק על ידי שותף
- מזהה IDFA ב-iOS
- מזהה פרסום ב-Android
- מזהה Roku
- מזהה Amazon Fire TV
- מזהה Xbox או מזהה מיקרוסופט
העלאה של מזהי משתמשים ב-Google
מזהי משתמשים ב-Google הם מזהים מוצפנים מהדומיין doubleclick.net.
כך מעלים מזהה משתמש ב-Google:
- הגדרת התאמה של קובצי Cookie באמצעות Google ואירוח של טבלת ההתאמה.
- משתמשים בטבלת ההתאמה כדי להמיר את מזהי המשתמשים למזהי משתמשים ב-Google.
- מעלים מזהי משתמשים ב-Google לרשימת המשתמשים.
לדוגמה, אם קיבלתם את ההודעה הבאה במהלך התאמת קובצי Cookie:
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
}
העלאת מזהים שסופקו על ידי שותפים
מזהים שסופקו על ידי השותף הם מזהים שנמצאים בדומיין של השותף. כך מעלים מזהה שסופק על ידי שותף:
מגדירים התאמה של קובצי Cookie עם Google, ומאפשרים ל-Google לארח את טבלת ההתאמה.
מעלים את המזהים שסופקו על ידי השותף לרשימת המשתמשים.
לדוגמה, אם מזהה המשתמש בדומיין שלכם מוגדר כ-
123456, אתם יכולים לאכלס אותו בטבלת ההתאמה המתארחת של Google באמצעות התאמת קובצי Cookie. תג ההתאמה צריך לכלול גרסה בקידוד base64 של המזהה שהוקצה לפרמטר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, ומוסיפה את המזהים לרשימת המשתמשים.
תהליך עבודה
כל הדוגמאות לבקשות ותשובות של הכלי להעלאה בכמות גדולה כתובות בפורמט טקסט. צריך לשלוח אותם כהודעות 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
שעברה סריאליזציה כמטען ייעודי (payload).
אם כל הפעולות הושלמו בהצלחה, תקבלו את התוצאה הבאה
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. הדרישה הזו חלה על כל הבקשות להעלאה בכמות גדולה.
במקרה של נתוני משתמשים שנדרשת לגביהם הסכמה ממשתמשי הקצה בהתאם למדיניות 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