Загрузить идентификаторы объявлений в списки пользователей

Вы можете использовать API массовой загрузки, чтобы добавлять и удалять идентификаторы объявлений в списках пользователей Авторизованных покупателей для таргетинга.

Вот пример URL-адреса API массовой загрузки HTTPS:

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

Конечная точка принимает запросы HTTPS POST.

Значением GoogleNetworkId должен быть ваш идентификатор сети сопоставления файлов cookie (NID), который уникально идентифицирует вашу учетную запись для массовой загрузки и сопоставления файлов cookie .

Полезная нагрузка запроса HTTPS POST представляет собой закодированный буфер протокола , который описывает списки, которые необходимо изменить. См. схему службы массовой загрузки в файле cookie-bulk-upload-proto.txt . Полезная нагрузка каждого запроса ограничена 100 КБ .

Чтобы узнать больше о том, как скомпилировать и использовать cookie-bulk-upload.proto для сериализации и анализа сообщений, см. руководство для предпочитаемого вами языка .

Вы можете загрузить следующие типы идентификаторов:

  • Идентификатор пользователя Google
  • Идентификатор, предоставленный партнером
  • Идентификатор iOS для iOS
  • Рекламный идентификатор Android
  • идентификатор Року
  • Идентификатор Amazon Fire TV
  • Xbox или идентификатор Microsoft

Загрузите идентификаторы пользователей Google

Идентификаторы пользователей Google — это зашифрованные идентификаторы домена doubleclick.net .

Вот как можно загрузить идентификатор пользователя Google:

  1. Настройте сопоставление файлов cookie с помощью Google и разместите таблицу соответствия.
  2. Используйте таблицу соответствия, чтобы преобразовать свои идентификаторы пользователей в идентификаторы пользователей Google.
  3. Загрузите идентификаторы пользователей Google в список пользователей.

Например, если во время сопоставления файлов cookie вы получаете следующее:

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 с помощью Google и разрешите Google разместить вашу таблицу соответствия.

  2. Загрузите идентификаторы, предоставленные партнером, в список пользователей.

    Например, если у вас есть идентификатор пользователя для вашего домена, установленный как 123456 , вы можете заполнить его в размещенной на Google таблице соответствия с помощью функции сопоставления файлов cookie. Тег соответствия должен включать веб-безопасную версию идентификатора, назначенного параметру google_hm , в кодировке Base64 , например следующую:

    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 и добавляет эти идентификаторы в ваш список пользователей.

Рабочий процесс

Все примеры запросов и ответов Массовой загрузки записываются в текстовом формате . Их необходимо отправлять в виде сериализованных сообщений протокольного буфера в конечную точку 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)

Партнеры, использующие 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