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

Bulk Uploader API を使用すると、認定バイヤーの広告 ID を追加、削除できます。 ターゲティングに使用できます。

HTTPS Bulk Uploader API のサンプルを次に示します。

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

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

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

HTTPS POST リクエストのペイロードは、 変更するリストを記述するプロトコル バッファ。 一括アップローダ サービスのスキーマについては、 cookie-bulk-upload-proto.txt.各 Pod のペイロード 上限は 100 KB です。

cookie-bulk-upload.proto をコンパイルして使用する方法について詳しくは、 メッセージのシリアル化と解析については、任意のチュートリアル 言語をご覧ください。

アップロードできる識別子の種類は次のとおりです。

  • Google ユーザー ID
  • パートナー指定の ID
  • iOS の IDFA
  • Android 広告 ID
  • Roku ID
  • Amazon Fire TV の ID
  • Xbox または 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 です。以下の手順を踏みます。 パートナー指定の ID をアップロードする:

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

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

    たとえば、ドメインのユーザー ID が 123456 に設定されている場合は、 Cookie マッチングを使って、Google がホストするマッチテーブルにデータを入力する。おすすめ度 タグにウェブセーフと base64 でエンコードされたバージョン 次のように、google_hm パラメータに割り当てられた ID。

    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 が作成され、ユーザーリストに追加されます。

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 を追加します。

で確認できます。

ワークフロー

一括アップロードのリクエストとレスポンスの例はすべて、テキスト 形式。送信するには、 シリアル化された Protocol Buffer メッセージとしてバルク Uploader 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 によって生成された ユーザー リストを指定することができます。

  #!/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 をご使用のパートナー様は、 一括アップロードの目的で Google とユーザーデータを共有する法的根拠 process_consent パラメータを含める必要があります。この要件は、すべての一括アップロードに適用される できます。

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