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

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

سير العمل

تمت كتابة جميع أمثلة طلبات برنامج التحميل المجمّع والرد عليه في Text التنسيق: عليك إرسال كرسائل التخزين المؤقت للبروتوكول المتسلسلة إلى مجمع نقطة نهاية واجهة برمجة تطبيقات القائم بالتحميل.

على سبيل المثال، لتحميل معرّف المعلِنين (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