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

אפשר להשתמש ב-Bulk Upload API באמצעות ה-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, מוסיפה את המזהים לרשימת המשתמשים.

תהליך עבודה

כל הדוגמאות לבקשות ולתגובות של מעלה הסרטון בכמות גדולה כתובות בטקסט פורמט. יש לשלוח אותן כהודעות טוריות של מאגר אחסון לפרוטוקולים נקודת קצה של Upload 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 מדיניות 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