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

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

Za pomocą interfejsu Bulk Upload API możesz dodawać identyfikatory reklam do list użytkowników w Authorized Buyers na potrzeby kierowania lub je z nich usuwać.

Oto przykładowy URL interfejsu HTTPS Bulk Upload API:

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

Punkt końcowy akceptuje żądania HTTPS POST.

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

Ładunek żądania HTTPS POST to zakodowany bufor protokołu opisujący listy do modyfikacji. 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 używaniu usługi cookie-bulk-upload.proto do szeregowania i analizowania wiadomości znajdziesz w samouczku dla wybranego języka.

Możesz przesyłać następujące typy identyfikatorów:

Identyfikator użytkownika Google
Identyfikator podawany przez partnera
IDFA (iOS)
Identyfikator wyświetlania reklam na urządzeniach z Androidem
Identyfikator Roku
Identyfikator Amazon Fire TV
Xbox lub Microsoft ID

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:

Skonfiguruj dopasowywanie plików cookie w Google i przeprowadź hostowanie tabeli odpowiedników.
Użyj tabeli odpowiedników, by 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 dane:

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

Parametr google_gid jest zaszyfrowanym identyfikatorem użytkownika Google.

Aby dodać go do listy użytkowników, skopiuj go 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 podawane przez partnera to identyfikatory w domenie partnera. Aby przesłać identyfikator przekazywany przez partnera:

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

Jeśli na przykład masz identyfikator użytkownika w domenie ustawiony na 123456, możesz wypełnić go w hostowanej przez Google tabeli odpowiedników za pomocą dopasowywania plików cookie. Tag dopasowania powinien zawierać zabezpieczoną w internecie wersję identyfikatora zakodowaną w formacie base64, przypisaną 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
}
```
Google przekształca listę użytkowników z identyfikatorów dostarczonych przez partnera na identyfikatory użytkowników Google i dodaje te identyfikatory do Twojej listy.

Prześlij identyfikatory wyświetlania reklam na Androida lub IDFA

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

Prześlij identyfikator urządzenia za pomocą narzędzia UpdateUsersDataRequest:

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

Google przekształca 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 narzędzia do przesyłania zbiorczego są zapisane w formacie tekstowym. Musisz je wysyłać jako zserializowane komunikaty Buffer protokołu do punktu końcowego interfejsu Bulk Uploader API.

Aby np. przesłać identyfikator IDFA i identyfikator podany przez partnera do listy 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 zserializowanym komunikatem UpdateUsersDataRequest jako ładunkiem.

Jeśli wszystkie operacje zakończą się powodzeniem, UpdateUsersDataResponse pojawi się taki komunikat:

status: NO_ERROR

Jeśli niektóre operacje zakończyły się powodzeniem, odpowiedź będzie zawierać błąd UpdateUsersDataResponse z informacją o błędzie w przypadku 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 się nie udała, odpowiedź będzie zawierać polecenie UpdateUsersDataResponse z wartością status ustawioną na BAD_COOKIE:

status: BAD_COOKIE

Przykład

Oto przykładowy skrypt w języku Python, który pokazuje, jak można użyć biblioteki wygenerowanej przez plik cookie-bulk-upload.proto do wypełnienia listy użytkowników danym identyfikatorem 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 żądaniu przesyłania zbiorczego

Partnerzy, którzy korzystają z interfejsu Bulk Upload API, muszą wykazać, że mają odpowiednią podstawę prawną do udostępniania Google danych użytkownika na potrzeby przesyłania zbiorczego. W tym celu muszą użyć parametru „process_consent” Dotyczy to wszystkich żądań przesyłania zbiorczego.

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 wyrazić jego zgodę przez ustawienie zasady process_consent=True.

W przypadku danych użytkownika, które nie podlegają wymaganiom w zakresie zgody użytkownika, partnerzy muszą za pomocą ustawienia process_consent=True wskazać, że zgoda na wykorzystywanie danych nie jest wymagana.

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

status: MISSING_CONSENT_WILL_BE_DROPPED

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

status: MISSING_CONSENT