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