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

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

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

في ما يلي نموذج لعنوان URL لواجهة برمجة تطبيقات HTTPS Bulk Upload API:

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
رقم التعريف الذي يقدّمه الشريك
معرِّف المعلِنين (IDFA) لنظام التشغيل iOS
المعرِّف الإعلاني على Android
رقم تعريف Roku
رقم تعريف Amazon Fire TV
Xbox أو Microsoft ID

تحميل أرقام تعريف مستخدمي 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
}

تحميل أرقام التعريف التي يقدّمها الشركاء

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

يمكنك إعداد ميزة مطابقة ملفات تعريف الارتباط مع 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، ويضيف أرقام التعريف إلى قائمة المستخدمين.

سير العمل

تتم كتابة جميع أمثلة طلبات التحميل المجمَّع وردودها بتنسيق نصي. عليك إرسالها في شكل رسائل مخزن مؤقت للبروتوكول المتسلسلة إلى نقطة نهاية واجهة برمجة التطبيقات 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

مثال

هذا مثال على نص برمجي في لغة بايثون يوضح كيفية استخدام المكتبة التي تم إنشاؤها بواسطة 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. ينطبق هذا الشرط على جميع طلبات التحميل المجمّع.

بالنسبة إلى بيانات المستخدمين التي تتطلب موافقة المستخدم في الاتحاد الأوروبي وفقًا لما تفرضه "سياسة موافقة المستخدم في الاتحاد الأوروبي" (يُرجى الاطّلاع على 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