Halaman ini diterjemahkan oleh Cloud Translation API.

Upload ID iklan ke daftar pengguna

Anda dapat menggunakan Bulk Uploader API untuk menambahkan dan menghapus ID iklan ke daftar pengguna Authorized Buyers untuk penargetan. Anda tidak dapat menggunakan Authorized Buyers Bulk Uploader API untuk mengubah daftar audiens Display & Video 360.

Berikut adalah contoh URL Bulk Uploader API HTTPS:

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

Endpoint menerima permintaan POST HTTPS.

Nilai untuk GoogleNetworkId harus berupa ID Jaringan Pencocokan Cookie (NID) yang mengidentifikasi akun Anda secara unik untuk Uploader Massal dan Pencocokan Cookie.

Payload permintaan HTTPS POST adalah buffering protokol dienkode yang menjelaskan daftar yang akan diubah. Lihat skema untuk layanan Uploader Massal di cookie-bulk-upload-proto.txt. Payload setiap permintaan dibatasi hingga 100 KB.

Untuk mempelajari lebih lanjut cara mengompilasi dan menggunakan cookie-bulk-upload.proto guna melakukan serialisasi dan mengurai pesan, lihat tutorial untuk bahasa pilihan Anda.

Anda dapat mengupload jenis ID berikut:

ID Pengguna Google
ID yang disediakan partner
IDFA iOS
ID iklan Android
ID Roku
ID Amazon Fire TV
ID Xbox atau Microsoft

Upload ID pengguna Google

ID pengguna Google adalah ID terenkripsi dari domain doubleclick.net.

Berikut cara mengupload ID pengguna Google:

Siapkan Pencocokan Cookie dengan Google dan hosting tabel pencocokan.
Gunakan tabel pencocokan untuk mengonversi User-ID Anda menjadi User-ID Google.
Upload ID Pengguna Google ke daftar pengguna.

Misalnya, jika Anda menerima hal berikut selama Pencocokan Cookie:

https://ad.network.com/pixel?google_gid=CAESEHIV8HXNp0pFdHgi2rElMfk&google_cver=1

Parameter google_gid adalah ID Pengguna Google yang dienkripsi.

Untuk menambahkannya ke daftar pengguna, salin ke isi UpdateUsersDataRequest:

ops {
  user_id: "CAESEHIV8HXNp0pFdHgi2rElMfk"
  user_list_id: 111
  delete: false
  user_id_type: GOOGLE_USER_ID
}

Upload ID yang diberikan partner

ID yang diberikan partner adalah ID yang berada di domain milik partner. Berikut cara mengupload ID yang disediakan partner:

Siapkan Pencocokan Cookie dengan Google, dan izinkan Google menghosting tabel pencocokan Anda.
Upload ID yang diberikan partner ke daftar pengguna.

Misalnya, jika Anda memiliki ID pengguna untuk domain yang ditetapkan sebagai 123456, Anda dapat mengisinya ke tabel pencocokan yang dihosting Google dengan Pencocokan Cookie. Tag kecocokan Anda harus menyertakan versi berenkode base64 yang aman untuk web dari ID yang ditetapkan ke parameter google_hm, seperti berikut ini:
```
https://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=MTIzNDU2&google_cm
```
Kemudian, Anda dapat mengupload ID yang disediakan partner ke daftar pengguna dengan UpdateUsersDataRequest:
```
ops {
 user_id: "123456"
 user_list_id: 123
 delete: false
 user_id_type: PARTNER_PROVIDED_ID
}
```
Kemudian, Google akan menerjemahkan daftar pengguna dari ID yang diberikan partner ke ID pengguna Google, dan menambahkan ID tersebut ke daftar pengguna Anda.

Upload ID iklan Android atau IDFA

Anda juga dapat mengupload ID perangkat.

Upload ID perangkat dengan UpdateUsersDataRequest:

ops {
 user_id: "2024D65F-EBBD-11FF-23AB-823FC255913A"
 user_list_id: 111
 delete: false
 user_id_type: IDFA
}

Kemudian, Google menerjemahkan daftar pengguna dari ID perangkat ke ID pengguna Google, dan menambahkan ID tersebut ke daftar pengguna Anda.

Alur kerja

Semua contoh permintaan dan respons Uploader Massal ditulis dalam Format Teks. Anda harus mengirimkannya sebagai pesan Protocol Buffer serial ke endpoint Bulk Uploader API.

Misalnya, untuk mengupload IDFA dan ID yang diberikan partner ke daftar pengguna 123, buat 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

Kemudian, kirim permintaan POST HTTPS dengan pesan UpdateUsersDataRequest serialisasi sebagai payload.

Jika semua operasi berhasil, Anda akan mendapatkan UpdateUsersDataResponse berikut:

status: NO_ERROR

Jika beberapa operasi berhasil, respons akan menyertakan UpdateUsersDataResponse dengan error untuk setiap operasi yang gagal:

status: PARTIAL_SUCCESS
errors {
  user_id: "1234567"
  error_code: UNKNOWN_ID
  user_id_type: PARTNER_PROVIDED_ID
}

Jika tidak ada operasi yang berhasil, respons akan menyertakan UpdateUsersDataResponse dengan status ditetapkan ke BAD_COOKIE:

status: BAD_COOKIE

Contoh

Ini adalah contoh skrip Python yang menunjukkan cara menggunakan library yang dibuat oleh cookie-bulk-upload.proto untuk mengisi daftar pengguna dengan ID tertentu menggunakan layanan uploader massal:

  #!/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)

Memproses Izin dalam Permintaan Upload Massal

Partner yang menggunakan Bulk Upload API harus menunjukkan bahwa mereka memiliki dasar hukum yang tepat untuk membagikan data pengguna kepada Google untuk tujuan Upload Massal menggunakan parameter process_consent. Persyaratan ini berlaku untuk semua permintaan Upload Banyak.

Untuk data pengguna yang memerlukan izin pengguna akhir sebagaimana diwajibkan oleh Kebijakan Izin Pengguna Uni Eropa Google (lihat https://www.google.com/about/company/user-consent-policy/) atau menurut hukum setempat lainnya, partner diwajibkan untuk mendapatkan izin pengguna akhir dan menunjukkan izin yang dikumpulkan dengan menetapkan process_consent=True.

Untuk data pengguna yang tidak tunduk pada persyaratan izin pengguna akhir, partner diwajibkan untuk menunjukkan bahwa izin tidak diperlukan dengan menetapkan process_consent=True.

Permintaan yang tidak memiliki process_consent akan difilter dan menampilkan error berikut:

status: MISSING_CONSENT_WILL_BE_DROPPED

Permintaan yang process_consent ditetapkan ke false akan difilter dan menampilkan error berikut:

status: MISSING_CONSENT