Puoi utilizzare l'API Bulk Uploader per aggiungere e rimuovere ID annuncio dagli elenchi di utenti di Authorized Buyers per il targeting. Non puoi utilizzare l'API Bulk Uploader di Authorized Buyers per modificare gli elenchi dei segmenti di pubblico di Display & Video 360.
Ecco un esempio di URL dell'API HTTPS Bulk Uploader:
https://cm.g.doubleclick.net/upload?nid={GoogleNetworkId}
L'endpoint accetta le richieste POST HTTPS.
Il valore di GoogleNetworkId
deve essere l'ID rete con corrispondenza dei cookie (NID),
che identifica in modo univoco il tuo account per il caricamento collettivo e la
corrispondenza dei cookie.
Il payload della richiesta POST HTTPS è un buffer di protocollo codificato che descrive gli elenchi da modificare. Vedi lo schema per il servizio di caricamento collettivo 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
serializzare e analizzare i messaggi, guarda il tutorial per la tua lingua
preferita.
Puoi caricare i seguenti tipi di identificatori:
- ID utente Google
- ID fornito dal partner
- IDFA per iOS
- ID pubblicità Android
- ID Roku
- ID Amazon Fire TV
- ID Xbox o Microsoft
Carica gli ID utente Google
Gli ID utente Google sono ID criptati provenienti dal 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.
- Caricare gli ID utente Google nell'elenco degli 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 di UpdateUsersDataRequest
:
ops {
user_id: "CAESEHIV8HXNp0pFdHgi2rElMfk"
user_list_id: 111
delete: false
user_id_type: GOOGLE_USER_ID
}
Carica gli ID forniti dai partner
Gli ID forniti dal partner sono ID appartenenti al dominio del partner. Ecco come caricare un ID fornito dal partner:
Configura la corrispondenza dei cookie con Google e consenti a Google di ospitare la tua tabella delle corrispondenze.
Carica gli ID forniti dal partner nell'elenco degli utenti.
Ad esempio, se hai impostato uno User-ID per il tuo dominio su
123456
, puoi compilarlo nella tabella delle corrispondenze ospitata da Google con Corrispondenza dei cookie. Il tag di corrispondenza deve includere una versione sicura per il web codificata in Base64 dell'ID assegnato al parametrogoogle_hm
, come riportato di seguito: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 converte poi l'elenco di utenti dagli ID forniti dai partner agli ID utente Google e aggiunge gli ID all'elenco degli utenti.
Carica IDFA o 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 converte poi l'elenco degli utenti dagli ID dispositivo agli ID utente Google e aggiunge gli ID all'elenco degli utenti.
Flusso di lavoro
Tutti gli esempi di richieste e risposte per il caricamento collettivo sono scritti in formato di testo. Devi inviarli come messaggi Protocol Buffer serializzati all'endpoint API Bulk Uploader.
Ad esempio, per caricare un IDFA e un ID fornito dal partner nell'elenco 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 hanno esito positivo, ottieni quanto segue
UpdateUsersDataResponse
:
status: NO_ERROR
Se alcune operazioni hanno avuto esito positivo, la risposta include un 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 elemento
UpdateUsersDataResponse
con status
impostato su BAD_COOKIE
:
status: BAD_COOKIE
Esempio
Questo è uno script Python di esempio che mostra come utilizzare la libreria generata da cookie-bulk-upload.proto per completare un elenco di utenti con un determinato ID mediante 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)
Elabora il consenso nella richiesta di caricamento collettivo
I partner che utilizzano l'API Bulk Upload devono indicare di disporre del fondamento giuridico appropriato per condividere i dati utente con Google a fini di 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 (consultare https://www.google.com/about/company/user-consent-policy/) o da altre leggi locali, i partner sono tenuti a ottenere il consenso degli utenti finali e a indicare il consenso raccolto impostando process_consent=True
.
Per i dati utente che non sono soggetti ai requisiti relativi al consenso degli utenti finali,
i partner devono indicare che il consenso non è
obbligatorio 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