העלאת מזהי מודעות לרשימות משתמשים

אפשר להשתמש ב-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:

  1. הגדרת התאמה של קובצי Cookie באמצעות Google ואירוח של טבלת ההתאמה.
  2. משתמשים בטבלת ההתאמה כדי להמיר את מזהי המשתמשים למזהי משתמשים ב-Google.
  3. מעלים מזהי משתמשים ב-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
}

העלאת מזהים שסופקו על ידי שותפים

מזהים שסופקו על ידי השותף הם מזהים שנמצאים בדומיין של השותף. כך מעלים מזהה שסופק על ידי שותף:

  1. מגדירים התאמה של קובצי Cookie עם Google, ומאפשרים ל-Google לארח את טבלת ההתאמה.

  2. מעלים את המזהים שסופקו על ידי השותף לרשימת המשתמשים.

    לדוגמה, אם מזהה המשתמש בדומיין שלכם מוגדר כ-123456, אתם יכולים לאכלס אותו בטבלת ההתאמה המתארחת של Google באמצעות התאמת קובצי Cookie. תג ההתאמה צריך לכלול גרסה בקידוד base64 של המזהה שהוקצה לפרמטר google_hm, שמתאימה לשימוש באינטרנט, כמו בדוגמה הבאה:

    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 שעברה סריאליזציה כמטען ייעודי (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