تحميل أرقام تعريف الإعلانات إلى قوائم المستخدمين

يمكنك استخدام Bulk Uploader API لإضافة أرقام تعريف الإعلانات وإزالتها من قوائم المستخدمين في Authorized Buyers بغرض الاستهداف.

في ما يلي نموذج لعنوان URL لواجهة برمجة التطبيقات الخاصة بأداة التحميل المجمّع عبر HTTPS:

https://cm.g.doubleclick.net/upload?nid={GoogleNetworkId}

تقبل نقطة النهاية طلبات HTTPS POST.

يجب أن تكون قيمة GoogleNetworkId هي رقم تعريف شبكة مطابقة ملفات تعريف الارتباط (NID) الذي يحدّد حسابك بشكل فريد في "أداة التحميل المجمّع" ومطابقة ملفات تعريف الارتباط.

حمولة طلب HTTPS POST هي بروتوكول مخزّن مؤقت مرمّز يصف القوائم التي سيتم تعديلها. يمكنك الاطّلاع على مخطط خدمة "أداة التحميل المجمّع" في الملف cookie-bulk-upload-proto.txt. يقتصر حجم حمولة كل طلب على 100 كيلوبايت.

لمزيد من المعلومات حول كيفية تجميع واستخدام cookie-bulk-upload.proto لتسلسل الرسائل وتحليلها، يُرجى الاطّلاع على البرنامج التعليمي للغتك المفضّلة.

يمكنك تحميل أنواع المعرّفات التالية:

• معرّف مستخدم Google
• معرّف مقدَّم من الشريك
• معرّف المعلِن على iOS
• المعرّف الإعلاني على Android
• معرّف Roku
• معرّف Amazon Fire TV
• معرّف Xbox أو Microsoft

تحميل أرقام تعريف مستخدمي Google

أرقام تعريف مستخدمي Google هي أرقام تعريف مشفّرة من النطاق doubleclick.net.

في ما يلي كيفية تحميل رقم تعريف مستخدم Google:

1. إعداد ميزة مطابقة ملفات تعريف الارتباط مع Google واستضافة جدول المطابقة
2. استخدِم جدول المطابقة لتحويل أرقام تعريف المستخدمين إلى أرقام تعريف مستخدمين على Google.
3. حمِّل أرقام تعريف المستخدمين على Google إلى قائمة المستخدمين.

على سبيل المثال، إذا تلقّيت ما يلي أثناء عملية مطابقة ملفات تعريف الارتباط:

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. يمكنك إعداد مطابقة ملفات تعريف الارتباط مع Google والسماح لشركة Google باستضافة جدول المطابقة.

2. حمِّل أرقام التعريف المقدَّمة من الشريك إلى قائمة المستخدمين.

   على سبيل المثال، إذا كان لديك رقم تعريف مستخدم لنطاقك تم ضبطه على 123456، يمكنك ملء هذا الرقم في جدول المطابقة المستضاف من Google باستخدام ميزة "مطابقة ملفات تعريف الارتباط". يجب أن يتضمّن رمز مطابقة المستخدمين نسخة بترميز 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 المسلسلة كحمولة.

في حال نجحت كل العمليات، ستظهر لك النتيجة التالية 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)

معالجة الموافقة في طلب التحميل المجمّع

على الشركاء الذين يستخدمون واجهة برمجة التطبيقات لتحميل البيانات المجمّعة الإشارة إلى أنّ لديهم الأساس القانوني المناسب لمشاركة بيانات المستخدمين مع 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