이 페이지는 Cloud Translation API를 통해 번역되었습니다.

사용자 목록에 광고 ID 업로드

Bulk 업로더 API를 사용하여 타겟팅을 위해 Authorized Buyers 사용자 목록에 광고 ID를 추가하고 삭제할 수 있습니다. Authorized Buyers Bulk 업로더 API를 사용하여 Display & Video 360 잠재고객 목록을 수정할 수 없습니다.

다음은 샘플 HTTPS Bulk 업로더 API URL입니다.

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

엔드포인트는 HTTPS POST 요청을 수락합니다.

GoogleNetworkId의 값은 일괄 업로더 및 쿠키 매칭을 위해 계정을 고유하게 식별하는 쿠키 일치 네트워크 ID (NID)여야 합니다.

HTTPS POST 요청의 페이로드는 수정할 목록을 설명하는 인코딩된 프로토콜 버퍼입니다. cookie-bulk-upload-proto.txt에서 일괄 업로더 서비스의 스키마를 확인하세요. 각 요청의 페이로드는 100KB로 제한됩니다.

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를 업로드하는 방법은 다음과 같습니다.

Google에서 쿠키 매칭을 설정하고 데이터 이동 색인을 호스팅합니다.
데이터 이동 색인을 사용하여 사용자 ID를 Google 사용자 ID로 변환합니다.
Google 사용자 ID를 사용자 목록에 업로드합니다.

예를 들어 쿠키 매칭 중에 다음을 수신하는 경우:

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에서 쿠키 매칭을 설정하고 Google이 데이터 이동 색인을 호스팅하도록 허용합니다.
파트너가 제공한 ID를 사용자 목록에 업로드합니다.

예를 들어 도메인의 사용자 ID가 123456로 설정된 경우 Google의 호스팅된 데이터 이동 색인에서 쿠키 일치를 채울 수 있습니다. 일치 태그에는 다음과 같이 google_hm 매개변수에 할당된 웹 안전 base64 인코딩 버전의 ID가 포함되어야 합니다.
```
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 엔드포인트에 직렬화된 프로토콜 버퍼 메시지로 보내야 합니다.

예를 들어 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