広告 ID をユーザーリストにアップロードする

一括アップロード API を使用すると、ターゲティング用の認定バイヤー ユーザーリストに広告 ID を追加または削除できます。

HTTPS 一括アップロード API の URL の例を次に示します。

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

エンドポイントは HTTPS POST リクエストを受け付けます。

GoogleNetworkId の値は、一括アップローダーと Cookie マッチングのアカウントを一意に識別する Cookie マッチング ネットワーク ID(NID)にする必要があります。

HTTPS POST リクエストのペイロードは、変更するリストを記述するエンコードされたプロトコル バッファです。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 をアップロードする方法は次のとおりです。

  1. Google で Cookie マッチングを設定し、マッチテーブルをホストします。
  2. マッチテーブルを使用して、ユーザー ID を Google ユーザー ID に変換します。
  3. 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 です。パートナー提供の身分証明書をアップロードする方法は次のとおりです。

  1. Google でCookie マッチングを設定し、Google にマッチテーブルのホストを許可します。

  2. パートナーから提供された ID をユーザーリストにアップロードします。

    たとえば、ドメインのユーザー ID が 123456 として設定されている場合は、Cookie マッチングを使用して Google のホスト型マッチテーブルにその ID を入力できます。マッチタグには、google_hm パラメータに割り当てられた ID のウェブセーフな base64 エンコードされたバージョンを含める必要があります。次に例を示します。

    https://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=MTIzNDU2&google_cm
    
  3. パートナー提供の ID は、UpdateUsersDataRequest を使用してユーザーリストにアップロードできます。

    ops {
     user_id: "123456"
     user_list_id: 123
     delete: false
     user_id_type: PARTNER_PROVIDED_ID
    }
    
  4. Google は、パートナー提供の ID から Google ユーザー ID にユーザーリストを変換し、ID をユーザーリストに追加します。

IDFA または Android 広告 ID をアップロードする

デバイス ID をアップロードすることもできます。

  1. UpdateUsersDataRequest でデバイス ID をアップロードします。

    ops {
     user_id: "2024D65F-EBBD-11FF-23AB-823FC255913A"
     user_list_id: 111
     delete: false
     user_id_type: IDFA
    }
    
  2. Google は、ユーザーリストをデバイス ID から Google ユーザー ID に変換し、ID をユーザーリストに追加します。

ワークフロー

一括アップロードのリクエストとレスポンスの例はすべて、テキスト形式で記述されています。シリアル化された プロトコル バッファ メッセージとして一括アップロード 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
}

どのオペレーションも成功しなかった場合、レスポンスには statusBAD_COOKIE に設定された UpdateUsersDataResponse が含まれます。

status: BAD_COOKIE

次の Python スクリプトは、cookie-bulk-upload.proto によって生成されたライブラリを使用して、一括アップロード サービスを使用して特定の ID を持つユーザーリストにデータを入力する方法を示しています。

  #!/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_consentfalse に設定されているリクエストはフィルタされ、次のエラーが返されます。

status: MISSING_CONSENT