Formatar dados do usuário

A API Data Manager permite o upload de vários tipos de dados do usuário. Siga os requisitos de formatação, hash e codificação de cada elemento de dados para que eles sejam recebidos e processados corretamente.

• UserData: dados fornecidos pelo usuário, como endereço de e-mail ou número de telefone.

• IpData: dados de IP, como um endereço IP e carimbos de data/hora associados.

• PairData: IDs de Reconciliação de dados de identificação entre publishers e anunciantes (PAIR).

• MobileData: dados que identificam um dispositivo móvel.

Requisitos do UserData

Um objeto UserData é uma coleção de objetos UserIdentifier. Cada UserIdentifier tem exatamente um dos atributos na tabela a seguir.

UserIdentifier
email_address	Formato string Converter em minúsculas. Se o endereço de e-mail tiver o domínio gmail.com ou googlemail.com: Remova todos os pontos (.) antes do símbolo @. Remova o sinal de adição (+) da parte local e todos os caracteres que o seguem. Exemplo: [e-mail] → [e-mail] Se o endereço de e-mail tiver um domínio diferente de gmail.com ou googlemail.com, não remova pontos ou sinais de adição. Exemplo: [e-mail] → [e-mail] Espaço em branco Remova os espaços em branco à esquerda, à direita e intermediários. Hash Gere o hash usando o algoritmo SHA-256 e codifique os bytes de hash.
phone_number	Formato string Use o formato E.164. Inclua o sinal de adição (+) e o código do país. Todos os caracteres após o sinal de mais precisam ser dígitos. Por exemplo, o número de telefone dos EUA [phone] precisa ser formatado e normalizado para [phone]. Espaço em branco Remova os espaços em branco à esquerda e à direita. Hash Gere o hash usando o algoritmo SHA-256 e codifique os bytes de hash.
address	Objeto AddressInfo Consulte a especificação de formato AddressInfo.

Formato AddressInfo

Use as seguintes diretrizes de formatação para criar o atributo address de um UserIdentifier.

AddressInfo
given_name	Formato string Converter em minúsculas. Não inclua prefixos como Mrs.. Espaço em branco Remova os espaços em branco à esquerda e à direita. Hash Gere o hash usando o algoritmo SHA-256 e codifique os bytes de hash.
family_name	Formato string Converter em minúsculas. Não inclua sufixos como Jr.. Espaço em branco Remova os espaços em branco à esquerda e à direita. Hash Gere o hash usando o algoritmo SHA-256 e codifique os bytes de hash.
region_code	Formato string Um código ISO-3166-1 alpha-2 de dois caracteres. Espaço em branco Remova os espaços em branco à esquerda e à direita. Hash Não use hash em region_code.
postal_code	Formato string São permitidos códigos postais internacionais e ZIP codes dos EUA. Para endereços dos EUA, use 5 dígitos ou 5 dígitos seguidos por uma extensão de 4 dígitos. O uso de uma extensão de 4 dígitos pode melhorar sua taxa de correspondência. Para todos os outros países, não use extensões de código postal. Espaço em branco Remova os espaços em branco à esquerda e à direita. Hash Não use hash em postal_code.
address_line	Formato string Usado apenas para o Google Analytics. Nome da rua e número do endereço do usuário. Converter em minúsculas. Remoção de caracteres de símbolo. Espaço em branco Remova os espaços em branco à esquerda e à direita. Hash Gere o hash usando o algoritmo SHA-256 e codifique os bytes de hash.
city	Formato string Usado apenas para o Google Analytics. A cidade do endereço do usuário. Converter em minúsculas. Remoção de caracteres de símbolo. Espaço em branco Remova os espaços em branco à esquerda e à direita. Hash Não use hash em city.
administrative_area	Formato string Usado apenas para o Google Analytics. A área político-administrativa (estado ou província) do endereço do usuário. Use a abreviação de duas letras (por exemplo, ca) ou o nome completo (por exemplo, california). Converter em minúsculas. Remoção de caracteres de símbolo. Espaço em branco Remova os espaços em branco à esquerda e à direita. Hash Não use hash em administrative_area.

Requisitos do IpData

Um objeto IpData tem os seguintes atributos.

IpData
ip_address	Formato string Endereço IPv4 ou IPv6. Para endereços IPv6, as letras maiúsculas ou minúsculas não importam. Espaço em branco Remova os espaços em branco à esquerda e à direita. Hash Não use hash em ip_address.

Requisitos do PairData

Preencha o campo pair_ids de um objeto PairData com uma lista de IDs. Formate cada elemento da lista seguindo estas etapas:

1. Gere hash dos dados de PII fornecidos pelo clean room usando o algoritmo SHA-256.

2. Criptografe os bytes de hash com uma criptografia comutativa de EC usando a chave do publisher para a lista de usuários do PAIR.

3. Codifique os dados criptografados usando a codificação hexadecimal ou Base64.

Requisitos do MobileData

Preencha o campo mobile_ids de um objeto MobileData com uma lista de IDs digitais. Não criptografe IDs de dispositivos móveis com hash.

Formato de carimbo de data/hora

Se você usar o formato JSON para campos Timestamp, como timestamp e last_updated_timestamp de Event, use o formato RFC 3339. Veja alguns exemplos do horário UTC de 8 de agosto de 2025 às 17h18min44s291 no formato RFC 3339 e em diferentes fusos horários:

• Fuso horário UTC: 2025-08-08T17:18:44.291Z

• Fuso horário EDT, que estava 4 horas antes do UTC naquele momento: 2025-08-08T13:18:44.291-04:00

• Fuso horário PDT, que estava 7 horas antes do UTC naquele momento: 2025-08-08T10:18:44.291-07:00

• Fuso horário de Tóquio, Japão, que estava 9 horas à frente do UTC e não segue o horário de verão: 2025-08-08T22:18:44.291+09:00

Se você estiver usando o formato de buffer de protocolo, defina o seconds e, opcionalmente, o nanos ao criar o Timestamp. Confira os valores de seconds e nanos para o horário UTC de 8 de agosto de 2025, às 17h18m44s291:

• seconds: 1754683124

• nanos: 291000000

Codificação

Os requisitos de codificação variam dependendo se você criptografa ou não os dados do usuário:

• Dados do usuário não criptografados:codifique os bytes de hash SHA-256 usando a codificação hexadecimal (hex) ou a codificação Base64.

• Dados do usuário criptografados:se você criptografar os dados do usuário, será necessário codificar em Base64 os bytes de hash brutos antes da criptografia. A codificação hexadecimal não é compatível com o hash de pré-criptografia. Em seguida, é possível codificar o texto criptografado resultante usando a codificação hexadecimal ou Base64.

Observação: o caso da saída de codificação não importa ao usar a codificação hexadecimal.