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

אפשר להשתמש ב-Bulk למעלה API כדי להוסיף ולהסיר מזהי מודעות לרשימות משתמשים של Authorized Buyers לצורך טירגוט.

הנה דוגמה לכתובת 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 ID

העלאת מזהי משתמשים ב-Google

מזהי המשתמשים ב-Google הם מזהים מוצפנים מהדומיין doubleclick.net.

כך מעלים מזהה משתמש ב-Google:

  1. מגדירים Cookie matching (התאמה של קובצי 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 matching (התאמת קובצי 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, ומוסיפה את המזהים לרשימת המשתמשים שלכם.

העלאת מזהי פרסום של Android או IDFA

אפשר גם להעלות מזהי מכשירים.

  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 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 למטרות העלאה בכמות גדולה באמצעות הפרמטר Processing_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