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

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

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

تحميل أرقام تعريف مستخدِمي 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 متسلسلة إلى نقطة نهاية BulkUploader 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