Questa pagina è stata tradotta dall'API Cloud Translation.

Caricare gli ID annuncio negli elenchi di utenti

Puoi utilizzare l'API Bulk Uploader per aggiungere e rimuovere gli ID annuncio agli elenchi di utenti Authorized Buyers per il targeting.

Ecco un URL di esempio dell'API Bulk Uploader HTTPS:

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

L'endpoint accetta richieste POST HTTPS.

Il valore di GoogleNetworkId deve essere l'ID rete di corrispondenza dei cookie (NID) che identifica in modo univoco il tuo account per Bulk Uploader e Corrispondenza dei cookie.

Il payload della richiesta POST HTTPS è un buffer di protocollo codificato che descrive gli elenchi da modificare. Consulta lo schema del servizio Bulk Uploader in cookie-bulk-upload-proto.txt. Il payload di ogni richiesta è limitato a 100 KB.

Per scoprire di più su come compilare e utilizzare cookie-bulk-upload.proto per eseguire la serializzazione e l'analisi dei messaggi, consulta il tutorial per la lingua che preferisci.

Puoi caricare i seguenti tipi di identificatori:

ID utente Google
ID fornito dal partner
IDFA per iOS
ID pubblicità di Android
ID Roku
ID Amazon Fire TV
ID Xbox o Microsoft

Carica gli ID utente Google

Gli ID utente di Google sono ID criptati del dominio doubleclick.net.

Ecco come caricare un ID utente Google:

Configura la corrispondenza dei cookie con Google e ospita la tabella delle corrispondenze.
Utilizza la tabella delle corrispondenze per convertire gli ID utente in ID utente Google.
Carica gli ID utente di Google nell'elenco utenti.

Ad esempio, se durante la corrispondenza dei cookie ricevi quanto segue:

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

Il parametro google_gid è l'ID utente Google criptato.

Per aggiungerlo a un elenco di utenti, copialo nel corpo del messaggio UpdateUsersDataRequest:

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

Carica gli ID forniti dal partner

Gli ID forniti dal partner appartengono al dominio del partner. Ecco come caricare un documento di identità fornito dal partner:

Configura la corrispondenza dei cookie con Google e consenti a Google di ospitare la tabella delle corrispondenze.
Carica gli ID forniti dal partner nell'elenco di utenti.

Ad esempio, se hai un ID utente per il tuo dominio impostato su 123456, puoi completarlo nella tabella delle corrispondenze ospitata da Google con la corrispondenza dei cookie. Il tag di corrispondenza deve includere una versione codificata in base 64 sicura per il web dell'ID assegnato al parametro google_hm, ad esempio la seguente:
```
https://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=MTIzNDU2&google_cm
```

Puoi quindi caricare l'ID fornito dal partner in un elenco di utenti con UpdateUsersDataRequest:

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

Google traduce quindi l'elenco di utenti dagli ID forniti dal partner agli ID utente di Google e aggiunge gli ID all'elenco di utenti.

Carica gli IDFA o gli ID pubblicità Android

Puoi anche caricare gli ID dispositivo.

Carica l'ID dispositivo con UpdateUsersDataRequest:

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

Google traduce quindi l'elenco utenti dagli ID dispositivo agli ID utente di Google e li aggiunge all'elenco utenti.

Flusso di lavoro

Tutti gli esempi di richieste e risposte di Bulk Uploader sono scritti in Formato text. Devi inviarli come messaggi Protocol Buffer serializzati all'endpoint dell'API Bulk Uploader.

Ad esempio, per caricare un IDFA e un ID fornito dal partner nell'elenco di utenti 123, crea un 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

Quindi, invia una richiesta POST HTTPS con il messaggio UpdateUsersDataRequest serializzato come payload.

Se tutte le operazioni sono andate a buon fine, viene visualizzato quanto segue UpdateUsersDataResponse:

status: NO_ERROR

Se alcune operazioni sono andate a buon fine, la risposta include un messaggio UpdateUsersDataResponse con un errore per ogni operazione non riuscita:

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

Se nessuna delle operazioni è andata a buon fine, la risposta include un UpdateUsersDataResponse con status impostato su BAD_COOKIE:

status: BAD_COOKIE

Esempio

Questo è un esempio di script Python che mostra come utilizzare la libreria generata da cookie-bulk-upload.proto per compilare un elenco di utenti con un determinato ID utilizzando il servizio di caricamento collettivo:

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

Elaborare il consenso nella richiesta di caricamento collettivo

I partner che utilizzano l'API Bulk Upload devono indicare di disporre della base giuridica appropriata per condividere i dati utente con Google per il caricamento collettivo utilizzando il parametro process_consent. Questo requisito si applica a tutte le richieste di caricamento collettivo.

Per i dati utente che richiedono il consenso dell'utente finale, come richiesto dalle Norme relative al consenso degli utenti dell'UE di Google (consulta la pagina https://www.google.com/about/company/user-consent-policy/) o da altre leggi locali, i partner sono tenuti a ottenere il consenso dell'utente finale e a indicare il consenso raccolto impostando process_consent=True.

Per i dati utente non soggetti ai requisiti di consenso dell'utente finale, i partner sono tenuti a indicare che il consenso non è richiesto impostando process_consent=True.

Le richieste in cui manca process_consent verranno filtrate e restituiranno il seguente errore:

status: MISSING_CONSENT_WILL_BE_DROPPED

Le richieste in cui process_consent è impostato su false verranno filtrate e restituiranno il seguente errore:

status: MISSING_CONSENT