Esta página foi traduzida pela API Cloud Translation.

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

É possível usar a API Bulk Uploader para adicionar e remover IDs de anúncios das listas de usuários do Authorized Buyers para segmentação.

Confira um exemplo de URL da API do Bulk Uploader HTTPS:

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

O endpoint aceita solicitações POST HTTPS.

O valor de GoogleNetworkId precisa ser o ID de rede (NID, na sigla em inglês) da correspondência de cookies, que identifica exclusivamente sua conta para o Bulk Uploader e a correspondência de cookies.

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

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

Você pode fazer 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 do Roku
ID da Amazon Fire TV
ID do Xbox ou da Microsoft

Fazer upload de IDs de usuário do Google

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

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

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

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

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

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

Para adicionar o token 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 os IDs do próprio domínio do parceiro. Saiba como enviar um documento de identificação fornecido pelo parceiro:

Configure a correspondência de cookies com o Google e permita que ele hospede sua tabela de correspondências.
Carregue os IDs fornecidos pelo parceiro na lista de usuários.

Por exemplo, se você tiver um ID do usuário para seu domínio definido como 123456, será possível preenchê-lo na tabela de correspondências hospedada do Google com a correspondência de cookies. Sua 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 esta:
```
https://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=MTIzNDU2&google_cm
```

Em seguida, faça 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 traduz a lista de usuários dos IDs fornecidos pelo parceiro para IDs de usuários do Google e adiciona os IDs à sua lista de usuários.

Fazer upload de IDs de publicidade do IDFA ou 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 traduz a lista de usuários de IDs de dispositivos para IDs de usuários do Google e adiciona os IDs à sua lista de usuários.

Fluxo de trabalho

Todos os exemplos de solicitação e resposta do Bulk Uploader são escritos no Formato de texto. Você precisa enviá-los como mensagens serializadas de buffer de protocolo para o endpoint da API Bulk Uploader.

Por exemplo, para fazer 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ê vai receber a seguinte 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 sido bem-sucedida, a resposta incluirá um UpdateUsersDataResponse com status definido como BAD_COOKIE:

status: BAD_COOKIE

Exemplo

Este é um exemplo de script Python que demonstra como usar a biblioteca gerada por cookie-bulk-upload.proto para preencher uma lista de usuários com um determinado ID usando o serviço de uploader 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 o consentimento na 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 Bulk Upload usando o parâmetro process_consent. Esse requisito se aplica a todos os pedidos de upload em massa.

Para dados do usuário que exigem consentimento do usuário final, conforme exigido pela Política de consentimento de usuários da União Europeia do Google (consulte https://www.google.com/about/company/user-consent-policy/) ou por outras leis locais, os parceiros precisam receber 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 serão filtradas e retornarão o seguinte erro:

status: MISSING_CONSENT