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

ניתן להשתמש ב-Bulk Upload API כדי להוסיף ולהסיר מזהי מודעות לרשימות משתמשים של Authorized Buyers לצורך טירגוט. לא ניתן להשתמש ב-Authorized Buyers Bulk Upload API כדי לשנות את רשימות הקהלים ב-Display & Video 360.

לפניכם כתובת URL לדוגמה של HTTPS Bulk Upload API:

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 או 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 מתרגמת את רשימת המשתמשים ממזהים שסופקו על ידי שותפים למזהי User-ID של 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.

לדוגמה, כדי להעלות לרשימת המשתמשים 123 IDFA ומזהה שסופק על ידי שותף, יוצרים 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 לצורך העלאה בכמות גדולה, באמצעות הפרמטר progress_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