Vous pouvez utiliser l'API Bulk Upload pour ajouter et supprimer des ID d'annonces dans les listes d'utilisateurs Authorized Buyers à des fins de ciblage. Vous ne pouvez pas utiliser l'API Bulk Upload d'Authorized Buyers pour modifier des listes d'audience Display & Video 360.
Voici un exemple d'URL de l'API de transfert groupé HTTPS:
https://cm.g.doubleclick.net/upload?nid={GoogleNetworkId}
Le point de terminaison accepte les requêtes HTTPS POST.
La valeur de GoogleNetworkId
doit être votre ID de réseau de mise en correspondance des cookies (NID, Cookie Matching Network ID), qui identifie de manière unique votre compte pour l'outil d'importation groupée et la mise en correspondance des cookies.
La charge utile de la requête HTTPS POST est un tampon de protocole encodé qui décrit les listes à modifier. Consultez le schéma du service d'importation groupée dans cookie-bulk-upload-proto.txt. La charge utile de chaque requête est limitée à 100 Ko.
Pour en savoir plus sur la compilation et l'utilisation de cookie-bulk-upload.proto
pour sérialiser et analyser les messages, consultez le tutoriel pour le langage de votre choix.
Vous pouvez importer les types d'identifiants suivants:
- ID utilisateur Google
- ID fourni par le partenaire
- IDFA pour iOS
- Identifiant publicitaire Android
- ID Roku
- Identifiant Amazon Fire TV
- Xbox ou ID Microsoft
Importer des ID utilisateur Google
Les ID utilisateur Google sont des ID chiffrés provenant du domaine doubleclick.net
.
Pour importer un ID utilisateur Google:
- Configurez la mise en correspondance des cookies avec Google et hébergez la table des correspondances.
- Utilisez votre tableau des correspondances pour convertir vos ID utilisateur en ID utilisateur Google.
- Importez des ID utilisateur Google dans la liste d'utilisateurs.
Par exemple, si vous recevez les informations suivantes lors de la lecture des cookies:
https://ad.network.com/pixel?google_gid=CAESEHIV8HXNp0pFdHgi2rElMfk&google_cver=1
Le paramètre google_gid
est l'ID utilisateur Google chiffré.
Pour l'ajouter à une liste d'utilisateurs, copiez-le dans le corps de UpdateUsersDataRequest
:
ops {
user_id: "CAESEHIV8HXNp0pFdHgi2rElMfk"
user_list_id: 111
delete: false
user_id_type: GOOGLE_USER_ID
}
Importer des ID fournis par des partenaires
Les ID fournis par le partenaire sont ceux rattachés au domaine du partenaire. Pour importer un ID fourni par le partenaire:
Configurez la mise en correspondance des cookies avec Google et autorisez-le à héberger votre table des correspondances.
Importez vos ID fournis par des partenaires dans la liste des utilisateurs.
Par exemple, si l'ID utilisateur de votre domaine est défini sur
123456
, vous pouvez l'insérer dans le tableau des correspondances hébergé de Google à l'aide de la mise en correspondance des cookies. Votre balise de correspondance doit inclure une version Web encodée en base64 de l'ID attribué au paramètregoogle_hm
, comme suit:https://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=MTIzNDU2&google_cm
Vous pouvez ensuite importer l'ID fourni par le partenaire dans une liste d'utilisateurs avec
UpdateUsersDataRequest
:ops { user_id: "123456" user_list_id: 123 delete: false user_id_type: PARTNER_PROVIDED_ID }
Google convertit ensuite la liste d'utilisateurs des ID fournis par les partenaires en ID utilisateur Google, puis ajoute les ID à votre liste d'utilisateurs.
Importer des IDFA ou des identifiants publicitaires Android
Vous pouvez également importer des ID d'appareils.
Importer l'ID de l'appareil avec
UpdateUsersDataRequest
:ops { user_id: "2024D65F-EBBD-11FF-23AB-823FC255913A" user_list_id: 111 delete: false user_id_type: IDFA }
Google convertit ensuite la liste d'utilisateurs des ID d'appareil en ID utilisateur Google, puis ajoute les ID à votre liste d'utilisateurs.
Workflow
Tous les exemples de requêtes et de réponses de l'outil Bulk Upload sont écrits au format texte. Vous devez les envoyer sous forme de messages de tampon de protocole sérialisés au point de terminaison de l'API Bulk Uploader.
Par exemple, pour importer un IDFA et un ID fourni par le partenaire dans la liste d'utilisateurs 123
, créez 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
Envoyez ensuite une requête HTTPS POST avec le message UpdateUsersDataRequest
sérialisé en tant que charge utile.
Si toutes les opérations aboutissent, vous obtenez le UpdateUsersDataResponse
suivant:
status: NO_ERROR
Si certaines opérations ont abouti, la réponse inclut un UpdateUsersDataResponse
avec une erreur pour chaque opération ayant échoué:
status: PARTIAL_SUCCESS
errors {
user_id: "1234567"
error_code: UNKNOWN_ID
user_id_type: PARTNER_PROVIDED_ID
}
Si aucune des opérations n'a abouti, la réponse inclut un UpdateUsersDataResponse
avec status
défini sur BAD_COOKIE
:
status: BAD_COOKIE
Exemple
Voici un exemple de script Python montrant comment utiliser la bibliothèque générée par cookie-bulk-upload.proto pour renseigner une liste d'utilisateurs avec un ID donné à l’aide du service d’importation groupée:
#!/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)
Traiter une demande d'importation groupée de consentement
Les partenaires qui utilisent l'API Bulk Upload doivent indiquer qu'ils disposent d'une base juridique pour partager des données utilisateur avec Google à des fins d'importation groupée à l'aide du paramètre "process_consent". Cette exigence s'applique à toutes les demandes d'importation groupée.
Pour les données utilisateur nécessitant le consentement de l'utilisateur final, conformément aux Règles relatives au consentement de l'utilisateur dans l'UE de Google (voir https://www.google.com/about/company/user-consent-policy/) ou en vertu d'autres lois locales, les partenaires sont tenus d'obtenir le consentement de l'utilisateur final et d'indiquer son consentement en définissant process_consent=True
.
Pour les données utilisateur qui ne sont pas soumises aux exigences de consentement des utilisateurs finaux, les partenaires doivent indiquer que le consentement n'est pas requis en définissant process_consent=True
.
Les requêtes pour lesquelles process_consent
est manquant seront filtrées et renvoient l'erreur suivante:
status: MISSING_CONSENT_WILL_BE_DROPPED
Les requêtes pour lesquelles process_consent
est défini sur false
seront filtrées et renvoient l'erreur suivante:
status: MISSING_CONSENT