این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

شناسه های تبلیغاتی را در لیست کاربران آپلود کنید

شما می‌توانید از API آپلودکننده انبوه برای اضافه کردن و حذف شناسه‌های تبلیغ به فهرست کاربران خریداران مجاز برای هدف‌گیری استفاده کنید.

در اینجا یک نمونه URL از API آپلودکننده انبوه HTTPS آورده شده است:

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

نقطه پایانی درخواست‌های HTTPS POST را می‌پذیرد.

مقدار GoogleNetworkId باید شناسه شبکه تطبیق کوکی (NID) شما باشد که به طور منحصر به فرد حساب شما را برای Bulk Uploader و Cookie Matching مشخص می‌کند.

بار داده‌ی درخواست HTTPS POST یک بافر پروتکل کدگذاری شده است که لیست‌هایی را که باید اصلاح شوند، توصیف می‌کند. طرحواره‌ی سرویس Bulk Uploader را در cookie-bulk-upload-proto.txt مشاهده کنید. بار داده‌ی هر درخواست به ۱۰۰ کیلوبایت محدود می‌شود.

برای کسب اطلاعات بیشتر در مورد نحوه کامپایل و استفاده از cookie-bulk-upload.proto برای سریال‌سازی و تجزیه پیام‌ها، به آموزش مربوط به زبان مورد نظر خود مراجعه کنید.

شما می‌توانید انواع شناسه‌های زیر را آپلود کنید:

شناسه کاربری گوگل
مدرک شناسایی ارائه شده توسط شریک
آی‌او‌اس
شناسه تبلیغاتی اندروید
شناسه روکو
شناسه تلویزیون آمازون فایر
ایکس‌باکس یا شناسه مایکروسافت

شناسه‌های کاربری گوگل را آپلود کنید

شناسه‌های کاربری گوگل، شناسه‌های رمزگذاری‌شده از دامنه doubleclick.net هستند.

نحوه آپلود شناسه کاربری گوگل به شرح زیر است:

تطبیق کوکی‌ها با گوگل را تنظیم کنید و جدول تطبیق را میزبانی کنید.
از جدول تطابق خود برای تبدیل شناسه‌های کاربری خود به شناسه‌های کاربری گوگل استفاده کنید.
شناسه‌های کاربری گوگل را به فهرست کاربران آپلود کنید.

برای مثال، اگر در طول تطبیق کوکی‌ها با خطای زیر مواجه شوید:

https://ad.network.com/pixel?google_gid=CAESEHIV8HXNp0pFdHgi2rElMfk&google_cver=1

پارامتر google_gid شناسه کاربری رمزگذاری شده گوگل است.

برای افزودن آن به لیست کاربران، آن را در بدنه UpdateUsersDataRequest کپی کنید:

ops {
  user_id: "CAESEHIV8HXNp0pFdHgi2rElMfk"
  user_list_id: 111
  delete: false
  user_id_type: GOOGLE_USER_ID
}

مدارک شناسایی ارائه شده توسط شریک را آپلود کنید

شناسه‌های ارائه شده توسط شریک، شناسه‌هایی هستند که تحت دامنه خود شریک قرار دارند. در اینجا نحوه آپلود شناسه ارائه شده توسط شریک آمده است:

تطبیق کوکی‌ها با گوگل را تنظیم کنید و به گوگل اجازه دهید جدول تطبیق شما را میزبانی کند.
شناسه‌های ارائه شده توسط شریک خود را در فهرست کاربران بارگذاری کنید.
برای مثال، اگر شناسه کاربری دامنه شما 123456 است، می‌توانید آن را در جدول تطابق میزبانی‌شده گوگل با استفاده از Cookie Matching وارد کنید. برچسب تطابق شما باید شامل یک نسخه کدگذاری‌شده 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
}
```
سپس گوگل فهرست کاربران را از شناسه‌های ارائه شده توسط شریک به شناسه‌های کاربری گوگل ترجمه می‌کند و شناسه‌ها را به فهرست کاربران شما اضافه می‌کند.

شناسه‌های تبلیغاتی IDFA یا Android را بارگذاری کنید

همچنین می‌توانید شناسه‌های دستگاه را بارگذاری کنید.

شناسه دستگاه را با UpdateUsersDataRequest آپلود کنید:

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

سپس گوگل فهرست کاربران را از شناسه‌های دستگاه به شناسه‌های کاربری گوگل ترجمه می‌کند و شناسه‌ها را به فهرست کاربران شما اضافه می‌کند.

گردش کار

تمام مثال‌های درخواست و پاسخ Bulk Uploader در قالب متن نوشته شده‌اند. شما باید آنها را به صورت پیام‌های سریالی Protocol Buffer به نقطه پایانی API Bulk Uploader ارسال کنید.

برای مثال، برای آپلود یک 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 به عنوان payload ارسال کنید.

اگر همه عملیات موفقیت‌آمیز باشد، 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)

پردازش درخواست آپلود انبوه با رضایت

شرکایی که از API آپلود انبوه استفاده می‌کنند باید با استفاده از پارامتر 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