Esta página foi traduzida pela API Cloud Translation.

Fazer o upload de IDs de anúncios para listas de usuários

Use a API Bulk Upload para adicionar e remover IDs de anúncios de listas de usuários do Authorized Buyers para segmentação. Não é possível usar a API Bulk superior do Authorized Buyers para modificar as listas de público-alvo do Display & Video 360.

Este é um exemplo de URL da API Bulk Upload em HTTPS:

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

O endpoint aceita solicitações HTTPS POST.

O valor de GoogleNetworkId deve ser seu ID de rede de correspondência de cookie (NID, na sigla em inglês), que identifica sua conta de forma exclusiva para a ferramenta de upload em massa e a Correspondência de cookie.

O payload da solicitação POST HTTPS é um buffer de protocolo codificado que descreve as listas a serem modificadas. Consulte o esquema para o serviço de upload em massa em cookie-bulk-upload-proto.txt. O payload de cada solicitação é limitado a 100 KB.

Para saber mais sobre como compilar e usar o cookie-bulk-upload.proto para serializar e analisar mensagens, consulte o tutorial da sua linguagem preferida.

É possível fazer o upload dos seguintes tipos de identificadores:

ID do usuário do Google
ID fornecido pelo parceiro
IDFA do iOS
ID de publicidade do Android
ID Roku
ID do Amazon Fire TV
ID do Xbox ou da Microsoft

Fazer upload de IDs de usuários do Google

Os IDs de usuário do Google são criptografados do domínio doubleclick.net.

Veja como fazer o upload de um ID de usuário do Google:

Configure a Correspondência de cookie com o Google e hospede a tabela de correspondências.
Use a tabela de correspondências para converter seus IDs de usuário em IDs de usuário do Google.
Faça o upload dos IDs de usuário do Google para a lista de usuários.

Por exemplo, se você receber o seguinte durante a correspondência de cookie:

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

O parâmetro google_gid é o ID do usuário criptografado do Google.

Para adicioná-lo a uma lista de usuários, copie-o para o corpo UpdateUsersDataRequest:

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

Fazer upload de IDs fornecidos pelo parceiro

Os IDs fornecidos pelo parceiro são aqueles que pertencem ao próprio domínio do parceiro. Confira como fazer upload de um ID fornecido pelo parceiro:

Configure a Correspondência de cookie com o Google e permita que o Google hospede sua tabela de correspondências.
Faça upload dos IDs fornecidos pelo parceiro para a lista de usuários.

Por exemplo, se você tiver um ID do usuário para seu domínio definido como 123456, poderá preenchê-lo na tabela de correspondências hospedada do Google com a correspondência de cookie. A tag de correspondência precisa incluir uma versão codificada em base64 segura para a Web do ID atribuído ao parâmetro google_hm, como a seguinte:
```
https://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=MTIzNDU2&google_cm
```
Depois, você pode fazer upload do ID fornecido pelo parceiro para uma lista de usuários com UpdateUsersDataRequest:
```
ops {
 user_id: "123456"
 user_list_id: 123
 delete: false
 user_id_type: PARTNER_PROVIDED_ID
}
```
Em seguida, o Google converte a lista de usuários de IDs fornecidos por parceiros em IDs de usuário do Google e adiciona esses IDs à sua lista.

Fazer o upload do IDFA ou dos IDs de publicidade do Android

Também é possível fazer upload de IDs de dispositivos.

Faça upload do ID do dispositivo com UpdateUsersDataRequest:

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

Em seguida, o Google converte a lista de usuários de IDs de dispositivos em IDs de usuário do Google e adiciona esses IDs à sua lista de usuários.

Fluxo de trabalho

Todos os exemplos de solicitação e resposta do Upload em massa são escritos em formato de texto. É preciso enviá-las como mensagens serializadas do buffer de protocolo para o endpoint da API Bulk Uploader.

Por exemplo, para fazer o upload de um IDFA e um ID fornecido pelo parceiro para a lista de usuários 123, crie um 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

Em seguida, envie uma solicitação POST HTTPS com a mensagem UpdateUsersDataRequest serializada como payload.

Se todas as operações forem bem-sucedidas, você receberá UpdateUsersDataResponse:

status: NO_ERROR

Se algumas das operações tiverem sido bem-sucedidas, a resposta incluirá um UpdateUsersDataResponse com um erro para cada operação com falha:

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

Se nenhuma das operações tiver êxito, a resposta incluirá um UpdateUsersDataResponse com status definido como BAD_COOKIE:

status: BAD_COOKIE

Exemplo

Este é um exemplo de script Python que demonstra como você pode usar a biblioteca gerada por cookie-bulk-upload.proto para preencher uma lista de usuários com determinado ID usando o serviço de upload em massa:

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

Processar solicitação de upload em massa

Os parceiros que usam a API Bulk Upload precisam indicar que têm a base legal adequada para compartilhar dados do usuário com o Google para fins de upload em massa usando o parâmetro process_consent. Esse requisito se aplica a todas as solicitações de upload em massa.

No caso de dados que exigem o consentimento do usuário final, conforme exigido pela Política de consentimento de usuários da União Europeia do Google (acesse https://www.google.com/about/company/user-consent-policy/) ou por outras leis locais, os parceiros precisam ter o consentimento do usuário final e indicar o consentimento coletado definindo process_consent=True.

Para dados do usuário que não estão sujeitos aos requisitos de consentimento do usuário final, os parceiros precisam indicar que o consentimento não é necessário definindo process_consent=True.

As solicitações em que process_consent está ausente serão filtradas e retornarão o seguinte erro:

status: MISSING_CONSENT_WILL_BE_DROPPED

As solicitações em que process_consent está definido como false são filtradas e retornam o seguinte erro:

status: MISSING_CONSENT