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