您可以使用 Bulk Manager API 為 Authorized Buyers 使用者名單新增及移除廣告 ID,以便指定目標。您無法使用 Authorized Buyers Bulk Manager API 修改 Display & Video 360 目標對象名單。
以下是 HTTPS 大量上傳器 API 網址範例:
https://cm.g.doubleclick.net/upload?nid={GoogleNetworkId}
端點接受 HTTPS POST 要求。
GoogleNetworkId
的值應為 Cookie 比對網路 ID (NID),該 ID 可在大量上傳者和 Cookie 比對中識別您的帳戶。
HTTPS POST 要求的酬載是經過編碼的通訊協定緩衝區,用於描述要修改的清單。請參閱 cookie-bulk-upload-proto.txt 中的大量上傳工具服務的結構定義。每個要求的酬載大小上限為 100 KB。
如要進一步瞭解如何編譯及使用 cookie-bulk-upload.proto
來序列化及剖析訊息,請參閱您的偏好語言的教學課程。
您可以上傳下列 ID 類型:
- Google 使用者 ID
- 合作夥伴提供的 ID
- iOS 廣告識別碼
- Android 廣告 ID
- Roku ID
- Amazon Fire TV ID
- Xbox 或 Microsoft ID
上傳 Google 使用者 ID
Google 使用者 ID 是來自 doubleclick.net
網域的加密 ID。
上傳 Google 使用者 ID 的方法如下:
- 使用 Google 設定 Cookie 比對,並代管對照表。
- 使用對照表將使用者 ID 轉換為 Google User ID。
- 將 Google User 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
,則該 ID 便可在 Google 的代管對照表中填入 Cookie 比對。比對標記應包含指派給google_hm
參數的 ID 網路安全 base64 編碼版本,如下所示:https://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=MTIzNDU2&google_cm
接著,您可以使用
UpdateUsersDataRequest
將合作夥伴提供的 ID 上傳至使用者名單: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 加進使用者名單。
工作流程
所有大量上傳者要求和回應範例皆以文字格式編寫。您必須將這些項目以序列化通訊協定緩衝區訊息傳送至 Bulk Uploader API 端點。
舉例來說,如要上傳廣告識別碼和合作夥伴提供的 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
接著傳送 HTTPS POST 要求,並以序列化的 UpdateUsersDataRequest
訊息做為酬載。
如果所有作業都成功,您會收到下列 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
範例
這是 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 的《歐盟地區使用者同意授權政策》(請參閱 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