Ta strona została przetłumaczona przez Cloud Translation API.

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

Za pomocą interfejsu Bulk Uploader API możesz dodawać i usuwać identyfikatory reklam do list użytkowników Authorized Buyers na potrzeby kierowania.

Oto przykładowy adres URL interfejsu API Bulk Uploader w protokole HTTPS:

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

Punkt końcowy akceptuje żądania POST HTTPS.

Wartością w polu GoogleNetworkId powinien być identyfikator sieci dopasowania plików cookie (NID), który jednoznacznie identyfikuje Twoje konto w ramach narzędzia do 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 Bulk Uploader znajdziesz w pliku cookie-bulk-upload-proto.txt. Ładunek każdego żądania jest ograniczony do 100 KB.

Aby dowiedzieć się więcej o kompilowaniu i używaniu biblioteki cookie-bulk-upload.proto do serializacji i analizowania wiadomości, zapoznaj się z samouczkiem w wybranym języku.

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

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

Przesyłanie identyfikatorów użytkowników Google

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

Aby przesłać identyfikator użytkownika Google:

Skonfiguruj dopasowywanie plików cookie w Google i hostuj tabelę odpowiedników.
Użyj tabeli dopasowania, aby przekonwertować identyfikatory użytkowników na identyfikatory użytkowników Google.
Prześlij identyfikatory użytkowników Google na listę użytkowników.

Jeśli na przykład podczas dopasowywania plików cookie otrzymasz takie informacje:

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

Parametr google_gid to zaszyfrowany identyfikator użytkownika Google.

Aby dodać go do listy użytkowników, skopiuj go do UpdateUsersDataRequest:

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

Przesyłanie identyfikatorów podanych przez partnera

Identyfikatory podawane przez partnera to identyfikatory w domenie partnera. Aby przesłać identyfikator podany przez partnera:

Skonfiguruj dopasowywanie plików cookie w Google i zezwól Google na hostowanie tabeli odpowiedników.
Prześlij na listę użytkowników identyfikatory podane przez partnera.

Jeśli np. masz ustawiony identyfikator użytkownika w domenie jako 123456, możesz go wypełnić w hostowanej tabeli dopasowania Google za pomocą usługi dopasowywania plików cookie. Tag dopasowania powinien zawierać obsługiwaną w internecie wersję zakodowaną w base64 identyfikatora przypisanego do parametru google_hm, np.:
```
https://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=MTIzNDU2&google_cm
```
Następnie możesz przesłać identyfikator podany przez partnera na listę użytkowników za pomocą: UpdateUsersDataRequest:
```
ops {
 user_id: "123456"
 user_list_id: 123
 delete: false
 user_id_type: PARTNER_PROVIDED_ID
}
```
Następnie Google przekształca listę użytkowników z identyfikatorów partnera w identyfikatory użytkowników Google i dodaje je do listy użytkowników.

Przesyłanie identyfikatorów IDFA lub identyfikatorów wyświetlania reklam na urządzeniach z Androidem

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

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
}

Następnie Google przekształca listę użytkowników z identyfikatorów urządzeń w identyfikatory użytkowników Google i dodaje je do listy użytkowników.

Przepływ pracy

Wszystkie przykłady żądań i odpowiedzi Bulk Uploader są zapisane w formacie tekstowym. Musisz je wysłać jako zserializowane wiadomości Protocol Buffer do punktu końcowego interfejsu Bulk Uploader API.

Aby np. przesłać identyfikator IDFA i identyfikator podany przez partnera na listę użytkowników 123, 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 serializowanym komunikatem UpdateUsersDataRequest jako ładunkiem.

Jeśli wszystkie operacje zakończą się powodzeniem, otrzymasz te informacje:UpdateUsersDataResponse:

status: NO_ERROR

Jeśli niektóre operacje się powiodły, odpowiedź zawiera element UpdateUsersDataResponse z błędem dla każdej nieudanej operacji:

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

Jeśli żadna z operacji nie powiodła się, odpowiedź zawiera element UpdateUsersDataResponse z wartością status równą BAD_COOKIE:

status: BAD_COOKIE

Przykład

Oto przykładowy skrypt Pythona, który pokazuje, jak za pomocą biblioteki wygenerowanej przez plik cookie-bulk-upload.proto można wypełnić listę użytkowników o danym identyfikatorze za pomocą 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)

Przetwarzanie zgody w prośbie o przesyłanie zbiorcze

Partnerzy korzystający z interfejsu Bulk Upload API muszą za pomocą parametru process_consent wskazać, że mają odpowiednią podstawę prawną do udostępniania danych użytkowników Google na potrzeby przesyłania zbiorczego. To wymaganie dotyczy wszystkich próśb o przesłanie zbiorcze.

W przypadku danych użytkownika, które wymagają zgody użytkownika zgodnie z wymogami polityki Google w zakresie zgody użytkownika z UE (zob. https://www.google.com/about/company/user-consent-policy/) lub innych lokalnych przepisów, partnerzy muszą uzyskać zgodę użytkownika i wskazać tę zgodę, ustawiając wartość process_consent=True.

W przypadku danych użytkownika, które nie podlegają wymaganiom dotyczącym zgody użytkownika, partnerzy muszą wskazać, że zgoda nie jest wymagana, ustawiając opcję process_consent=True.

Żądania, w których brakuje parametru process_consent, zostaną odfiltrowane i zwrócą ten błąd:

status: MISSING_CONSENT_WILL_BE_DROPPED

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

status: MISSING_CONSENT