Upload ad IDs to user lists

You can use the Bulk Uploader API to add and remove ad IDs to Authorized Buyers user lists for targeting.

Here's a sample HTTPS Bulk Uploader API URL:

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

The endpoint accepts HTTPS POST requests.

The value for GoogleNetworkId should be your Cookie Matching Network ID (NID) which uniquely identifies your account for Bulk Uploader and Cookie Matching.

The HTTPS POST request's payload is an encoded protocol buffer that describes the lists to be modified. See the schema for the Bulk Uploader service in cookie-bulk-upload-proto.txt. The payload of each request is limited to 100 KB.

To learn more about how to compile and use cookie-bulk-upload.proto to serialize and parse messages, see the tutorial for your preferred language.

You can upload the following identifiers types:

Google user ID
Partner-provided ID
iOS IDFA
Android advertising ID
Roku ID
Amazon Fire TV ID
Xbox or Microsoft ID

Upload Google user IDs

Google user IDs are encrypted IDs from the doubleclick.net domain.

Here's how to upload a Google user ID:

Set up Cookie Matching with Google and host the match table.
Use your match table to convert your user IDs into Google User IDs.
Upload Google User IDs to the user list.

For example, if you receive the following during Cookie Matching:

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

The google_gid parameter is the encrypted Google User ID.

To add it to a user list, copy it to the UpdateUsersDataRequest body:

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

Upload partner-provided IDs

Partner-provided IDs are IDs under the partner's own domain. Here's how to upload a partner-provided ID:

Set up Cookie Matching with Google, and allow Google to host your match table.
Upload your partner-provided IDs to the user list.

For example, if you have a user ID for your domain set as 123456, you can populate it in Google's hosted match table with Cookie Matching. Your match tag should include a web-safe base64-encoded version of the ID assigned to the google_hm parameter, such as the following:
```
https://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=MTIzNDU2&google_cm
```

You can then upload the partner-provided ID to a user list with UpdateUsersDataRequest:

ops {
 user_id: "123456"
 user_list_id: 123
 delete: false
 user_id_type: PARTNER_PROVIDED_ID
}

Google then translates the user list from partner-provided IDs to Google user IDs, and adds the IDs to your user list.

Upload IDFA or Android advertising IDs

You can also upload device IDs.

Upload device ID with UpdateUsersDataRequest:

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

Google then translates the user list from device IDs to Google user IDs, and adds the IDs to your user list.

Workflow

All Bulk Uploader request and response examples are written in Text Format. You have to send them as serialized Protocol Buffer messages to the Bulk Uploader API endpoint.

For example, to upload an IDFA and partner-provided ID to user list 123, create an 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

Then, send an HTTPS POST request with the serialized UpdateUsersDataRequest message as the payload.

If all of the operations are successful, you get the following UpdateUsersDataResponse:

status: NO_ERROR

If some of the operations were successful, the response includes an UpdateUsersDataResponse with an error for each failed operation:

status: PARTIAL_SUCCESS
errors {
  user_id: "1234567"
  error_code: UNKNOWN_ID
  user_id_type: PARTNER_PROVIDED_ID
}

If none of the operations were successful, the response includes an UpdateUsersDataResponse with status set to BAD_COOKIE:

status: BAD_COOKIE

Example

This is an example Python script demonstrating how you can use the library generated by cookie-bulk-upload.proto to populate a user list with a given ID using the bulk uploader service:

  #!/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)

Process Consent In Bulk Upload Request

Partners using the Bulk Upload API must indicate that they have the proper legal basis to share user data with Google for Bulk Upload purposes using the process_consent parameter. This requirement applies to all Bulk Upload requests.

For user data that requires end-user consent as required by Google's EU User Consent Policy (see https://www.google.com/about/company/user-consent-policy/) or by other local laws, partners are required to obtain end-user consent and indicate gathered consent by setting process_consent=True.

For user data which is not subject to end-user consent requirements, partners are required to indicate that consent is not required by setting process_consent=True.

Requests where process_consent is missing will be filtered and return the following error:

status: MISSING_CONSENT_WILL_BE_DROPPED

Requests where process_consent is set to false will be filtered and return the following error:

status: MISSING_CONSENT