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

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

در اینجا یک نمونه URL API آپلود کننده انبوه 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 برای سریال سازی و تجزیه پیام ها، به آموزش زبان دلخواه خود مراجعه کنید.

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

  • شناسه کاربری گوگل
  • شناسه ارائه شده توسط شریک
  • iOS IDFA
  • شناسه تبلیغات اندروید
  • شناسه Roku
  • ID آمازون Fire TV
  • Xbox یا Microsoft ID

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

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

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

  1. Cookie Matching را با 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. Cookie Matching را با Google راه‌اندازی کنید و به Google اجازه دهید جدول مطابقت شما را میزبانی کند.

  2. شناسه های ارائه شده توسط شریک خود را در لیست کاربران آپلود کنید.

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

همچنین می توانید شناسه های دستگاه را آپلود کنید.

  1. شناسه دستگاه را با UpdateUsersDataRequest بارگذاری کنید:

    ops {
     user_id: "2024D65F-EBBD-11FF-23AB-823FC255913A"
     user_list_id: 111
     delete: false
     user_id_type: IDFA
    }
    
  2. سپس گوگل لیست کاربران را از شناسه های دستگاه به شناسه های کاربری گوگل ترجمه می کند و شناسه ها را به لیست کاربران شما اضافه می کند.

گردش کار

همه درخواست‌ها و نمونه‌های پاسخ انبوه آپلودگر در قالب متن نوشته شده‌اند. شما باید آنها را به عنوان پیام های بافر پروتکل سریالی به نقطه پایانی 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)


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