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

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

  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, ומוסיפה את המזהים לרשימת המשתמשים.

תהליך עבודה

כל הדוגמאות לבקשות ולתשובות של 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