一括アップローダ API を使用して、ターゲティング用の認定バイヤー ユーザーリストに広告 ID を追加したり、削除したりできます。
HTTPS 一括アップローダ API の URL の例を次に示します。
https://cm.g.doubleclick.net/upload?nid={GoogleNetworkId}
エンドポイントは HTTPS POST リクエストを受け付けます。
GoogleNetworkId の値は、一括アップローダと Cookie マッチングでアカウントを一意に識別する Cookie マッチング ネットワーク ID(NID)である必要があります。
HTTPS POST リクエストのペイロードは、変更するリストを記述するエンコードされたプロトコル バッファです。Bulk Uploader サービスのスキーマについては、cookie-bulk-upload-proto.txt をご覧ください。各リクエストのペイロードは 100 KB に制限されています。
cookie-bulk-upload.proto をコンパイルしてメッセージのシリアル化と解析に使用する方法について詳しくは、お好みの言語のチュートリアルをご覧ください。
アップロードできる識別子の種類は次のとおりです。
- Google ユーザー ID
- パートナー提供の ID
- iOS IDFA
- Android 広告 ID
- Roku ID
- Amazon Fire TV ID
- Xbox ID または Microsoft ID
Google ユーザー ID をアップロードする
Google ユーザー ID は、doubleclick.net ドメインの暗号化された ID です。
Google ユーザー ID をアップロードする手順は次のとおりです。
- Google で Cookie マッチングを設定し、マッチテーブルをホストします。
- 一致テーブルを使用して、ユーザー ID を Google ユーザー ID に変換します。
- Google ユーザー ID をユーザーリストにアップロードします。
たとえば、Cookie マッチング中に次の情報を受け取ったとします。
https://ad.network.com/pixel?google_gid=CAESEHIV8HXNp0pFdHgi2rElMfk&google_cver=1
google_gid パラメータは、暗号化された Google ユーザー ID です。
ユーザーリストに追加するには、UpdateUsersDataRequest の本文にコピーします。
ops {
user_id: "CAESEHIV8HXNp0pFdHgi2rElMfk"
user_list_id: 111
delete: false
user_id_type: GOOGLE_USER_ID
}
パートナー提供の ID をアップロードする
パートナー提供の ID は、パートナー自身のドメインの ID です。パートナーから提供された ID をアップロードする方法は次のとおりです。
Google との Cookie マッチングを設定し、Google がマッチテーブルをホストできるようにします。
パートナーから提供された ID をユーザーリストにアップロードします。
たとえば、ドメインのユーザー ID が
123456に設定されている場合、Cookie マッチングを使用して Google のホスト型マッチテーブルにデータを入力できます。一致タグには、google_hmパラメータに割り当てられた ID のウェブセーフな base64 エンコード バージョンを含める必要があります。例:https://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=MTIzNDU2&google_cmその後、パートナーから提供された ID を
UpdateUsersDataRequestを使用してユーザーリストにアップロードできます。ops { user_id: "123456" user_list_id: 123 delete: false user_id_type: PARTNER_PROVIDED_ID }Google は、パートナーから提供された ID を Google ユーザー ID に変換し、ユーザーリストに ID を追加します。
IDFA または Android 広告 ID をアップロードする
デバイス ID をアップロードすることもできます。
UpdateUsersDataRequestでデバイス ID をアップロードします。ops { user_id: "2024D65F-EBBD-11FF-23AB-823FC255913A" user_list_id: 111 delete: false user_id_type: IDFA }次に、Google はデバイス ID から Google ユーザー ID にユーザーリストを変換し、ID をユーザーリストに追加します。
ワークフロー
一括アップローダのリクエストとレスポンスの例はすべて、テキスト形式で記述されています。シリアル化された Protocol Buffer メッセージとして、一括アップローダ API エンドポイントに送信する必要があります。
たとえば、IDFA とパートナー提供の ID をユーザーリスト 123 にアップロードするには、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
次に、シリアル化された UpdateUsersDataRequest メッセージをペイロードとして HTTPS POST リクエストを送信します。
すべてのオペレーションが成功すると、次の UpdateUsersDataResponse が返されます。
status: NO_ERROR
一部のオペレーションが成功した場合、レスポンスには、失敗したオペレーションごとにエラーを含む UpdateUsersDataResponse が含まれます。
status: PARTIAL_SUCCESS
errors {
user_id: "1234567"
error_code: UNKNOWN_ID
user_id_type: PARTNER_PROVIDED_ID
}
オペレーションが成功しなかった場合、レスポンスには status が BAD_COOKIE に設定された UpdateUsersDataResponse が含まれます。
status: BAD_COOKIE
例
これは、cookie-bulk-upload.proto で生成されたライブラリを使用して、一括アップローダー サービスで指定された ID のユーザーリストにデータを入力する方法を示す Python スクリプトの例です。
#!/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)
一括アップロード リクエストで同意を処理する
Bulk Upload API を使用するパートナーは、process_consent パラメータを使用して、一括アップロードの目的でユーザーデータを Google と共有するための適切な法的根拠があることを示す必要があります。この要件は、すべての一括アップロード リクエストに適用されます。
Google の EU ユーザーの同意ポリシー(https://www.google.com/about/company/user-consent-policy/ を参照)またはその他の現地の法律でエンドユーザーの同意が必要なユーザーデータについては、パートナーはエンドユーザーの同意を取得し、process_consent=True を設定して取得した同意を示す必要があります。
エンドユーザーの同意要件の対象とならないユーザーデータについては、パートナーは process_consent=True を設定して同意が不要であることを示す必要があります。
process_consent が欠落しているリクエストはフィルタされ、次のエラーが返されます。
status: MISSING_CONSENT_WILL_BE_DROPPED
process_consent が false に設定されているリクエストはフィルタリングされ、次のエラーが返されます。
status: MISSING_CONSENT