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

Use a API BulkUpload para adicionar e remover IDs de anúncios no Authorized Buyers. listas de usuários para segmentação.

Este é um exemplo de URL da API BulkUpload de HTTPS:

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

O endpoint aceita solicitações POST HTTPS.

O valor de GoogleNetworkId precisa ser seu ID de rede de correspondência de cookie (NID, na sigla em inglês) que identifica exclusivamente sua conta para o upload em massa e Correspondência de cookie.

O payload da solicitação POST HTTPS é um valor buffer de protocolo que descreve as listas a serem modificadas. Veja o esquema do serviço de upload em massa na cookie-bulk-upload-proto.txt. O payload de cada solicitação é limitada a 100 KB.

Para saber mais sobre como compilar e usar cookie-bulk-upload.proto para serialize e analise mensagens, consulte o tutorial da sua idioma.

É 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 do Roku
  • ID do Amazon Fire TV
  • Xbox ou Microsoft ID

Fazer upload de IDs de usuários do Google

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

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

  1. Configure a Correspondência de cookie com o Google e hospede o tabela de correspondências.
  2. Use sua tabela de correspondências para converter seus IDs de usuário em IDs de usuário do Google.
  3. 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 de usuário do Google criptografado.

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 dos IDs fornecidos pelo parceiro

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

  1. Configurar a Correspondência de cookie com o Google e permitir Google para hospedar sua tabela de correspondências.

  2. Faça upload dos códigos fornecidos por parceiros para a lista de usuários.

    Por exemplo, se você tiver um ID de usuário para seu domínio definido como 123456, será possível preenchê-la na tabela de correspondências hospedada do Google com a correspondência de cookie. Combina com você deve incluir uma tag segura para a Web versão codificada em base64 do o ID atribuído ao parâmetro google_hm, como no exemplo a seguir:

    https://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=MTIzNDU2&google_cm
    
  3. 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
    }
    
  4. Depois, o Google converte a lista de usuários dos IDs fornecidos por parceiros para o Google. IDs de usuário e adiciona os IDs à sua lista de usuários.

Fazer upload do IDFA ou dos códigos de publicidade do Android

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

  1. Fazer 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
    }
    
  2. O Google converte a lista de usuários de IDs de dispositivos para IDs de usuários do Google. adiciona os IDs à sua lista de usuários.

.

Fluxo de trabalho

Todos os exemplos de solicitação e resposta da Ferramenta de upload em massa estão escritos em Texto Formato. Você deve enviar -os como mensagens serializadas do buffer de protocolo ao Endpoint da API Compose.

Por exemplo, para fazer o upload de um IDFA e 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

Depois, envie uma solicitação POST HTTPS com o UpdateUsersDataRequest serializado. como payload.

Se todas as operações forem bem-sucedidas, você receberá o 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 ê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 usar a biblioteca gerado por cookie-bulk-upload.proto para preencher um lista de usuários com um 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)

Os parceiros que usam a API Bulk Upload devem indicar que eles têm as base legal 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 todos os serviços de upload em massa, solicitações.

Para dados do usuário que exigem o consentimento do usuário final, conforme exigido pela UE do Google Política de consentimento do usuário (consulte https://www.google.com/about/company/user-consent-policy/) ou de acordo com a legislação local, os parceiros precisam ter o consentimento do usuário final e indicar o consentimento coletado definindo process_consent=True.

No caso de dados do usuário que não estão sujeitos aos requisitos de consentimento do usuário final, os parceiros devem indicar que o consentimento não é exigido pela configuração process_consent=True.

As solicitações em que process_consent estiver ausente serão filtradas e retornadas o seguinte erro:

status: MISSING_CONSENT_WILL_BE_DROPPED

As solicitações em que process_consent estiver definido como false serão filtradas e retorne o seguinte erro:

status: MISSING_CONSENT