Mit der Bulk Uploader API können Sie Anzeigen-IDs zu Authorized Buyers-Nutzerlisten für das Targeting hinzufügen oder daraus entfernen. Die Bulk Uploader API von Authorized Buyers kann nicht verwendet werden, um Display & Video 360-Zielgruppenlisten zu ändern.
Hier ist ein Beispiel für die URL der HTTPS Bulk Uploader API:
https://cm.g.doubleclick.net/upload?nid={GoogleNetworkId}
Der Endpunkt akzeptiert HTTPS-POST-Anfragen.
Der Wert für GoogleNetworkId
sollte Ihre Netzwerk-ID (Cookie Matching Network ID, NID) sein, mit der Ihr Konto für den Bulk-Upload und den Cookie-Abgleich eindeutig identifiziert wird.
Die Nutzlast der HTTPS-POST-Anfrage ist ein codierter Protokollpuffer, der die zu ändernden Listen beschreibt. Weitere Informationen finden Sie im Schema für den Bulk-Uploader-Dienst in der Datei cookie-bulk-upload-proto.txt. Die Nutzlast jeder Anfrage ist auf 100 KB begrenzt.
Weitere Informationen zum Kompilieren und Verwenden von cookie-bulk-upload.proto
zum Serialisieren und Parsen von Nachrichten finden Sie in der Anleitung für Ihre bevorzugte Sprache.
Sie können die folgenden Kennungstypen hochladen:
- Google-Nutzer-ID
- Vom Partner bereitgestellte ID
- IDFA für iOS
- Android-Werbe-ID
- Roku-ID
- Amazon Fire TV-ID
- Xbox- oder Microsoft-ID
Google-Nutzer-IDs hochladen
Google-Nutzer-IDs sind verschlüsselte IDs der Domain doubleclick.net
.
So laden Sie eine Google-Nutzer-ID hoch:
- Richten Sie den Cookie-Abgleich mit Google ein und hosten Sie die Match-Table.
- Verwenden Sie die Match-Table, um Ihre User-IDs in Google Nutzer-IDs umzuwandeln.
- Laden Sie Google Nutzer-IDs in die Nutzerliste hoch.
Angenommen, Sie erhalten während des Cookie-Abgleichs Folgendes:
https://ad.network.com/pixel?google_gid=CAESEHIV8HXNp0pFdHgi2rElMfk&google_cver=1
Der Parameter google_gid
ist die verschlüsselte Google Nutzer-ID.
Wenn Sie sie einer Nutzerliste hinzufügen möchten, kopieren Sie sie in den UpdateUsersDataRequest
-Text:
ops {
user_id: "CAESEHIV8HXNp0pFdHgi2rElMfk"
user_list_id: 111
delete: false
user_id_type: GOOGLE_USER_ID
}
Vom Partner bereitgestellte IDs hochladen
Vom Partner bereitgestellte IDs sind IDs unter der eigenen Domain des Partners. So laden Sie eine vom Partner bereitgestellte ID hoch:
Richten Sie den Cookie-Abgleich mit Google ein und erlauben Sie Google, die Match-Table zu hosten.
Laden Sie die von Partnern bereitgestellten IDs in die Nutzerliste hoch.
Wenn Sie beispielsweise die Nutzer-ID für Ihre Domain auf
123456
festgelegt haben, können Sie diese mit dem Cookie-Abgleich in die von Google gehostete Match-Table eintragen. Das Übereinstimmungs-Tag sollte eine websichere, base64-codierte Version der ID enthalten, die dem Parametergoogle_hm
zugewiesen ist. Beispiel:https://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=MTIzNDU2&google_cm
Anschließend können Sie die vom Partner bereitgestellte ID mit
UpdateUsersDataRequest
in eine Nutzerliste hochladen:ops { user_id: "123456" user_list_id: 123 delete: false user_id_type: PARTNER_PROVIDED_ID }
Google übersetzt dann die Nutzerliste von den vom Partner bereitgestellten IDs in Google-Nutzer-IDs und fügt die IDs Ihrer Nutzerliste hinzu.
IDFA- oder Android-Werbe-IDs hochladen
Sie können auch Geräte-IDs hochladen.
Geräte-ID mit
UpdateUsersDataRequest
hochladen:ops { user_id: "2024D65F-EBBD-11FF-23AB-823FC255913A" user_list_id: 111 delete: false user_id_type: IDFA }
Google übersetzt dann die Nutzerliste von Geräte-IDs in Google-Nutzer-IDs und fügt die IDs Ihrer Nutzerliste hinzu.
Workflow
Alle Beispiele für Bulk-Upload-Anfragen und -Antworten sind im Textformat verfasst. Sie müssen sie als serielle Protokollzwischenspeicher-Nachrichten an den API-Endpunkt für Bulk-Uploads senden.
Wenn Sie beispielsweise eine IDFA und eine von einem Partner bereitgestellte ID in die Nutzerliste 123
hochladen möchten, müssen Sie eine UpdateUsersDataRequest
erstellen:
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
Senden Sie dann eine HTTPS-POST-Anfrage mit der seriellen UpdateUsersDataRequest
-Nachricht als Nutzlast.
Wenn alle Vorgänge erfolgreich sind, wird das folgende UpdateUsersDataResponse
angezeigt:
status: NO_ERROR
Wenn einige der Vorgänge erfolgreich waren, enthält die Antwort ein UpdateUsersDataResponse
mit einem Fehler für jeden fehlgeschlagenen Vorgang:
status: PARTIAL_SUCCESS
errors {
user_id: "1234567"
error_code: UNKNOWN_ID
user_id_type: PARTNER_PROVIDED_ID
}
Wenn keiner der Vorgänge erfolgreich war, enthält die Antwort ein UpdateUsersDataResponse
, in dem status
auf BAD_COOKIE
gesetzt ist:
status: BAD_COOKIE
Beispiel
Dies ist ein Beispielskript in Python, das zeigt, wie Sie die von cookie-bulk-upload.proto generierte Bibliothek verwenden können, um mit dem Bulk-Uploader-Dienst eine Nutzerliste mit einer bestimmten ID zu füllen:
#!/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)
Einwilligung bei Bulk-Upload-Anfrage verarbeiten
Partner, die die Bulk Upload API verwenden, müssen angeben, dass sie die entsprechende Rechtsgrundlage haben, um Nutzerdaten für Bulk-Uploads mithilfe des Parameters „process_consent“ an Google weiterzugeben. Diese Anforderung gilt für alle Bulk-Upload-Anfragen.
Für Nutzerdaten, die gemäß der Richtlinie zur Einwilligung der Nutzer in der EU von Google (siehe https://www.google.com/about/company/user-consent-policy/) oder anderen lokalen Gesetzen erforderlich sind, müssen Partner die Endnutzereinwilligung einholen und ihre Einwilligung durch Festlegen von process_consent=True
angeben.
Für Nutzerdaten, die nicht der Einwilligungsanforderungen für Endnutzer unterliegen, müssen Partner durch Festlegen von process_consent=True
angeben, dass die Einwilligung nicht erforderlich ist.
Anfragen, bei denen process_consent
fehlt, werden gefiltert und geben den folgenden Fehler zurück:
status: MISSING_CONSENT_WILL_BE_DROPPED
Anfragen, bei denen process_consent
auf false
gesetzt ist, werden gefiltert und den folgenden Fehler zurückgegeben:
status: MISSING_CONSENT