Przesyłanie identyfikatorów reklam do list użytkowników

Za pomocą interfejsu Bulk Upload API możesz dodawać i usuwać identyfikatory reklam na listach użytkowników Authorized Buyers na potrzeby kierowania. Do modyfikowania list odbiorców Display & Video 360 nie można używać interfejsu Authorized Buyers Bulk Upload API.

Oto przykładowy adres URL interfejsu HTTPS Bulk Upload API:

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

Punkt końcowy akceptuje żądania HTTPS POST.

Wartość GoogleNetworkId powinna być identyfikatorem sieci dopasowywania plików cookie (NID), który jednoznacznie identyfikuje konto na potrzeby przesyłania zbiorczego i dopasowywania plików cookie.

Ładunek żądania HTTPS POST to zakodowany bufor protokołu, który opisuje listy do zmodyfikowania. Schemat usługi przesyłania zbiorczego znajdziesz w pliku cookie-bulk-upload-proto.txt. Ładunek każdego żądania jest ograniczony do 100 KB.

Więcej informacji o kompilowaniu i analizowaniu wiadomości za pomocą cookie-bulk-upload.proto znajdziesz w samouczku dotyczącym preferowanego języka.

Możesz przesyłać te typy identyfikatorów:

  • Identyfikator użytkownika Google
  • Identyfikator podany przez partnera
  • IDFA w iOS
  • Identyfikator wyświetlania reklam na urządzeniach z Androidem
  • Identyfikator Roku
  • Identyfikator Amazon Fire TV
  • Identyfikator Xbox lub Microsoft

Prześlij identyfikatory użytkowników Google

Identyfikatory użytkowników Google to zaszyfrowane identyfikatory z domeny doubleclick.net.

Aby przesłać identyfikator użytkownika Google:

  1. Skonfiguruj dopasowywanie plików cookie w Google i umieść na serwerze tabelę odpowiedników.
  2. Za pomocą tabeli odpowiedników przekonwertuj identyfikatory użytkowników na identyfikatory użytkowników Google.
  3. Prześlij identyfikatory użytkowników Google na listę użytkowników.

Jeśli na przykład podczas dopasowywania plików cookie uzyskasz te dane:

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

Parametr google_gid to zaszyfrowany identyfikator użytkownika Google.

Aby dodać ją do listy użytkowników, skopiuj ją do treści UpdateUsersDataRequest:

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

Prześlij identyfikatory podane przez partnera

Identyfikatory dostarczane przez partnera to identyfikatory należące do jego własnej domeny. Aby przesłać identyfikator podany przez partnera:

  1. Skonfiguruj dopasowywanie plików cookie w Google i zezwól Google na hostowanie Twojej tabeli odpowiedników.

  2. Prześlij na listę użytkowników identyfikatory dostarczane przez partnerów.

    Jeśli na przykład masz identyfikator użytkownika ustawiony jako 123456, możesz wypełnić go w tabeli odpowiedników hostowanej przez Google za pomocą dopasowywania plików cookie. Tag dopasowania powinien zawierać bezpieczną w internecie wersję identyfikatora przypisaną do parametru google_hm za pomocą zakodowanej w base64, np.:

    https://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=MTIzNDU2&google_cm

  3. Następnie możesz przesłać udostępniony przez partnera identyfikator na listę użytkowników za pomocą funkcji UpdateUsersDataRequest:

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

  4. Google przekształca listę użytkowników z identyfikatorów dostarczanych przez partnerów na identyfikatory użytkowników Google i dodaje je do Twojej listy.

Prześlij identyfikatory wyświetlania reklam IDFA lub identyfikatory wyświetlania reklam na urządzeniach z Androidem

Możesz też przesłać identyfikatory urządzeń.

  1. Prześlij identyfikator urządzenia za pomocą UpdateUsersDataRequest:

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

  2. Google konwertuje listę użytkowników z identyfikatorów urządzeń na identyfikatory użytkowników Google i dodaje te identyfikatory do Twojej listy.

Przepływ pracy

Wszystkie przykłady żądań i odpowiedzi dla narzędzia do przesyłania zbiorczego są zapisane w formacie tekstu. Musisz je wysłać jako zserializowane komunikaty Bufor protokołów do punktu końcowego interfejsu Bulk Uploader API.

Aby np. przesłać do listy użytkowników 123 identyfikator IDFA i identyfikator podany przez partnera, utwórz 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

Następnie wyślij żądanie HTTPS POST z zserializowaną wiadomością UpdateUsersDataRequest jako ładunkiem.

Jeśli wszystkie operacje się udają, otrzymasz ten komunikat (UpdateUsersDataResponse):

status: NO_ERROR

Jeśli niektóre operacje się udały, odpowiedź będzie zawierać UpdateUsersDataResponse z błędem w przypadku każdej z nich:

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

Jeśli żadna z operacji się nie uda, odpowiedź będzie zawierać element UpdateUsersDataResponse z atrybutem status ustawionym na BAD_COOKIE:

status: BAD_COOKIE

Przykład

To przykładowy skrypt w języku Python pokazujący, jak użyć biblioteki wygenerowanej przez plik cookie-bulk-upload.proto do wypełnienia listy użytkowników danym identyfikatorem przy użyciu usługi przesyłania zbiorczego:

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

Partnerzy korzystający z interfejsu Bulk Upload API muszą wskazać, że mają odpowiednią podstawę prawną do udostępniania Google danych użytkownika na potrzeby przesyłania zbiorczego. To wymaganie dotyczy wszystkich żądań zbiorczego przesyłania danych.

W przypadku danych użytkownika, które wymagają zgody użytkownika zgodnie z polityką Google w zakresie zgody użytkownika z UE (patrz: https://www.google.com/about/company/user-consent-policy/) lub innymi przepisami obowiązującymi w danym kraju, partnerzy muszą uzyskać zgodę użytkownika i wskazać jej udzieloną zgodę w ramach ustawienia process_consent=True.

W przypadku danych użytkownika, które nie podlegają wymogom dotyczącym zgody użytkownika, partnerzy muszą za pomocą ustawienia process_consent=True zaznaczyć, że zgoda użytkownika nie jest wymagana.

Żądania, w których brakuje process_consent, zostaną przefiltrowane i zwrócią ten błąd:

status: MISSING_CONSENT_WILL_BE_DROPPED

Żądania, w których process_consent ma wartość false, zostaną odfiltrowane i zwróci ten błąd:

status: MISSING_CONSENT