تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

يمكنك استخدام واجهة برمجة التطبيقات Bulk Uploader API لإضافة معرّفات الإعلانات وإزالتها من قوائم "المشترون المعتمَدون" المستخدمين لأغراض الاستهداف.

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

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

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

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

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

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

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

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

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

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

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

إعداد ميزة مطابقة ملفات تعريف الارتباط مع Google واستضافة جدول المطابقة
استخدِم جدول المطابقة لتحويل أرقام تعريف المستخدمين إلى أرقام تعريف مستخدمي Google.
حمِّل أرقام تعريف مستخدمي 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
}

تحميل مستندات تعريف قدّمها الشريك

المعرّفات التي يقدّمها الشريك هي معرّفات ضمن نطاق الشريك الخاص. في ما يلي كيفية uploadتحميل مستند تعريف يقدّمه الشريك:

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

على سبيل المثال، إذا كان لديك رقم تعريف مستخدم لنطاقك تم ضبطه على 123456، يمكنك ملؤه في جدول المطابقة المستضاف من Google باستخدام ميزة "مطابقة ملفات تعريف الارتباط". يجب أن تتضمّن علامة مطابقة إصدارًابترميز base64 ومتوافقًا مع الويب للمعرّف الذي تمّ تعيينه للمَعلمة google_hm، مثل ما يلي:
```
https://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=MTIzNDU2&google_cm
```
يمكنك بعد ذلك تحميل رقم التعريف الذي قدّمه الشريك إلى قائمة مستخدمين باستخدام UpdateUsersDataRequest:
```
ops {
 user_id: "123456"
 user_list_id: 123
 delete: false
 user_id_type: PARTNER_PROVIDED_ID
}
```
بعد ذلك، تُحوِّل Google قائمة المستخدمين من أرقام التعريف المقدَّمة من الشريك إلى أرقام تعريف مستخدمي Google، وتضيف أرقام التعريف إلى قائمة المستخدمين.

تحميل معرّفات IDFA أو معرّفات الإعلانات على Android

يمكنك أيضًا تحميل أرقام تعريف الأجهزة.

تحميل رقم تعريف الجهاز باستخدام UpdateUsersDataRequest:

ops {
 user_id: "2024D65F-EBBD-11FF-23AB-823FC255913A"
 user_list_id: 111
 delete: false
 user_id_type: IDFA
}

بعد ذلك، تحوّل 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)

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

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