A correspondência de dados fornecidos pelo usuário (UPDM) reúne dados próprios que você coletou sobre um usuário, como informações dos seus sites, apps ou lojas físicas, usando a atividade de login do usuário em todos os dados de anúncios do Google, incluindo dados de propriedade e operação do Google. Isso inclui dados comprados por produtos do Google Marketing Platform (GMP), por exemplo, o YouTube comprado usando o Display & Video 360. Outros produtos da GMP que não são de propriedade e operados pelo Google não são compatíveis.
Para se qualificar para a correspondência de dados fornecidos pelo usuário, o evento de anúncio precisa estar vinculado a um usuário conectado nos dados de anúncios do Google.
Neste documento, descrevemos o recurso de correspondência de dados fornecidos pelo usuário e fornecemos orientações sobre configuração e uso.
Visão geral da correspondência de nuvem privada
Para receber insights valiosos de publicidade, geralmente é necessário juntar dados de várias fontes. Criar uma solução própria para esse problema de pipeline de dados exige um investimento significativo de tempo e engenharia. A Private Cloud Match no Ads Data Hub simplifica esse processo, fornecendo um modelo de consulta do Ads Data Hub para criar uma tabela de correspondência no BigQuery que pode ser usada nas suas consultas do Ads Data Hub para associar os dados de anúncios aos seus dados próprios. Enriquecer suas consultas com dados próprios pode oferecer experiências do cliente mais avançadas e é mais resistente a mudanças no rastreamento de anúncios em todo o setor.
Como a correspondência de dados fornecidos pelo usuário só está disponível no inventário pertencente e operado pelo Google para usuários conectados, ela não é afetada pela descontinuação dos cookies de terceiros. Como é mais resistente a mudanças do setor do que os dados de terceiros, ele pode fornecer insights mais detalhados, o que pode levar a um maior engajamento do cliente.
Resumo do processo
- Configuração da ingestão de dados e correspondência
- Você: verifique se os dados próprios estão no BigQuery e se a conta de serviço tem acesso de leitura a eles. Consulte Configurar a ingestão de dados.
- Transferência e correspondência de dados próprios
- Você formata e faz upload dos seus dados próprios para o conjunto de dados do BigQuery.
- Você inicia uma solicitação de correspondência de dados criando uma e definindo uma programação.
- O Google mescla os dados do seu projeto com os dados de propriedade do Google que contêm o ID do usuário do Google e os dados fornecidos pelo usuário com hash para criar e atualizar tabelas de correspondência.
- Consulte Ingerir dados próprios.
- Consultas em andamento no Ads Data Hub, com base em dados correspondentes
- Você executa consultas nas tabelas de correspondências da mesma forma que faz as consultas normais no Ads Data Hub. Consulte Dados de correspondência de consultas.
Saiba mais sobre as normas de privacidade
Coleta de dados do cliente
Ao usar a correspondência de dados fornecidos pelo usuário, você precisa fazer o upload de dados próprios. Podem ser informações coletadas nos seus sites, apps, lojas físicas ou qualquer informação que um cliente tenha compartilhado diretamente com você.
Você precisa:
- Divulgar na Política de Privacidade que você compartilha dados dos clientes com terceiros para a realização de serviços no seu nome e que obtém o consentimento para esse compartilhamento, conforme os requisitos legais.
- Usar somente a API ou a interface aprovada do Google para fazer o upload de dados dos clientes.
- Obedecer a todas as leis e regulamentações aplicáveis, incluindo códigos de autorregulação ou do setor.
Confirmação do consentimento para uso de dados próprios
Para conseguir usar seus dados próprios no Ads Data Hub, você precisa confirmar que obteve o consentimento necessário para compartilhar dados dos usuários finais do EEE com o Google conforme a Política de consentimento de usuários da União Europeia e a política do Ads Data Hub. Essa exigência vale para cada conta do Ads Data Hub e precisa ser atualizada toda vez que você faz upload de novos dados próprios. Qualquer usuário pode fazer essa confirmação em nome da conta como um todo.
As mesmas regras para consultas dos Serviços do Google aplicáveis às consultas de análises também valem para as consultas de UPDM. Por exemplo, não é possível realizar consultas entre serviços envolvendo usuários que estejam no EEE na hora de criar uma tabela de correspondência.
Para saber como confirmar o consentimento no Ads Data Hub, consulte Requisitos de conhecimento no Espaço Econômico Europeu.
Tamanho dos dados
Para proteger a privacidade do usuário final, a correspondência de dados fornecidos pelo usuário aplica estes requisitos ao tamanho dos seus dados:
- Você precisa fazer upload de pelo menos 1.000 registros na sua lista de usuários.
Configurar a ingestão de dados
Antes de começar, verifique se:
- Seus dados próprios precisam estar no BigQuery. Se você tiver um perímetro do VPC-SC, esses dados próprios precisarão estar localizados no VPC-SC.
- Sua conta de serviço do Ads Data Hub precisa ter acesso de leitura aos dados próprios.
- Os dados próprios precisam ser formatados e criptografados corretamente. Consulte a próxima seção para saber mais.
Além disso, o Private Cloud Match não tem outra integração. Se você pode executar uma consulta de análise, pode executar uma consulta do Private Cloud Match.
Transferir e combinar dados próprios
Permissões de origem e requisitos de conexão
As conexões do Ads Data Hub usam a conta de serviço mostrada em Configurações > Detalhes > Conta de serviço (geralmente service-<number>@gcp-sa-adsdatahub.iam.gserviceaccount.com). Conceda a ela estes papéis:
- Origem do BigQuery:
roles/bigquery.dataViewer(Visualizador de dados do BigQuery) no conjunto de dados ou na tabela de origem. - Origem do Cloud Storage:
roles/storage.objectViewer(Leitor de objetos do Storage) no bucket ou objeto de origem. - Destino da importação de dados próprios:
roles/bigquery.dataEditor(Editor de dados do BigQuery) no conjunto de dados de destino, se a tabela não estiver no conjunto de dados padrão.
Requisitos de campo e tipo de dados
Essas regras são para conexões na experiência atualizada de conexões. Eles dependem do tipo de conexão: Correspondência de dados fornecidos pelo usuário ou Dados próprios.
Correspondência de dados fornecidos pelo usuário (UPDM)
Mapeie user_id e pelo menos um destes: email, phone ou um endereço completo (first_name, last_name, country e zip_code). Se você mapear qualquer coluna de endereço, mapeie as quatro. Caso contrário, não será possível salvar a conexão. Não é possível
mudar o Tipo dessas colunas: é HASH para email, phone,
first_name e last_name, e STRING para user_id, country e
zip_code.
A coluna de origem que você mapeia para cada coluna de destino precisa conter o seguinte. Para formatar os valores, consulte Formatar dados para entrada.
| Coluna de destino | Valor da coluna de origem | Exemplo |
|---|---|---|
user_id |
Seu ID do usuário, em texto simples | customer-1234 |
email, phone, first_name, last_name |
O valor formatado, com hash SHA-256 e codificado em Base64 (44 caracteres). A codificação hexadecimal (64 caracteres) também funciona. | h5JGBrQTGorO7q6IaFMfu5cSqqB6XTp1aybOD11spnQ=, o hash de test@gmail.com |
country |
Um código de país de duas letras (ISO 3166-1 alfa-2), em texto simples. | US |
zip_code |
Um CEP ou código postal de até 20 caracteres (letras de A a Z, dígitos, espaços e hifens), em texto simples | 94043 |
- Gere hash dos valores na sua origem. O Connections não gera hash de
email,phone,first_nameoulast_name, mesmo que o Tipo seja HASH. Uma exceção: se a conexão foi movida para a experiência atualizada de conexões e um campo usou o hash de computação antes da mudança (o hash de computação gerou o hash da coluna para você), as conexões ainda vão gerar o hash desse campo. Mantenha os valores de origem desse campo sem hash, mas formatados. Consulte Conexões movidas. - Em uma tabela de origem do BigQuery, use colunas
STRING.email,phone,first_nameelast_nameprecisam serSTRING. Com outro tipo, comoINT64, não é possível salvar a conexão.user_idtambém pode serINT64ouBYTES. Um valorBYTESque não é texto UTF-8 se tornaNULL.zip_codetambém pode serINT64, mas umINT64não pode manter um zero à esquerda (02134é armazenado como2134). Portanto, esse CEP não pode corresponder. Armazene os CEPs comoSTRING.
- Atribua um ID do usuário a cada linha. Todas as linhas com um ID do usuário
NULLcontam como um usuário. Portanto, no máximo uma delas pode corresponder. O mesmo vale para todas as linhas com um ID do usuário vazio. - Seu ID do usuário passa a ser
BYTES. O Connections o converte emBYTES, o tipo de ID do usuário listado em Formatar dados para entrada, para que a coluna de origem possa permanecer comoSTRING. Por exemplo, o valorINT6442se tornab"42". Nas tabelas de correspondência do_updm, é a colunacustomer_data_user_id.CAST(my_data.user_id AS BYTES)falha para um IDINT64. Portanto, para mesclar em um, primeiro faça a transmissão paraSTRING:customer_data_user_id = CAST(CAST(my_data.user_id AS STRING) AS BYTES). - Um valor de e-mail, telefone ou endereço vazio ou formatado incorretamente não pode
corresponder, mas não falha na execução. A linha ainda pode corresponder aos
outros valores. Por exemplo, um e-mail em texto simples, o país
USAou o CEP94043.1351não podem corresponder. Para corresponder ao endereço, uma linha precisa ter valores válidos nas quatro colunas de endereço. - Em uma consulta de correspondência de nuvem privada, um valor no formato errado pode causar falha em toda a consulta. Isso se aplica se você criar a tabela de correspondência com a consulta
CREATE OR REPLACE TABLE adh.updm_match_tableno Ads Data Hub em vez de uma conexão. Por exemplo, um hash de e-mail que não tem 44 caracteres, como um codificado em hexadecimal, falha na consulta com um erro comoemail must be encoded using TO_BASE64(SHA256(email)). - Verifique sua taxa de correspondência. Por exemplo, use a consulta
Calcular taxa de correspondência. O Connections não informa valores que não podem ser correspondidos, então você recebe menos usuários correspondentes. Se 1.000
usuários ou menos corresponderem, a execução vai falhar com
Minimum match count check failed. - Use apenas uma conexão do UPDM por conta. As conexões da UPDM não têm tabela de destino. Cada conexão do UPDM em uma conta e cada consulta do Private Cloud Match grava a mesma tabela de correspondência, e cada execução bem-sucedida a substitui. Para combinar dados de várias fontes, combine-os primeiro em uma tabela ou arquivo.
Dados próprios
Para cada coluna, escolha um Tipo (Tipo de dados na página de detalhes da conexão). O Connections converte cada valor de origem para esse tipo, e a coluna de destino recebe o tipo do BigQuery listado aqui:
| Tipo | Coluna de destino | Valores que ele converte | Valores que se tornam NULL |
|---|---|---|---|
| STRING (padrão) | STRING |
Qualquer valor, como texto. No BigQuery, 123 se torna "123" e TRUE se torna "true". No Cloud Storage, o texto é mantido como está. |
Um valor BYTES que não é um texto UTF-8 |
| HASH | STRING |
Igual a STRING. O Connections não gera hash nem verifica o valor. | Igual a STRING |
| INTEGER | INT64 |
Números inteiros e texto numérico, como "42". No BigQuery, um decimal é truncado: 1.9 se torna 1. |
Outros valores, como "abc", TRUE ou uma data. Do Cloud Storage, também um decimal, como 1.9. |
| DOUBLE | FLOAT64 |
Números e textos numéricos, como "1.5" |
Outros valores, como TRUE ou uma data |
| DATA | DATE |
Valores DATE e texto de ano-mês-dia, como 2026-01-15 ou 2026-1-5. |
Outros valores, como 01/15/2026, 20260115 ou um valor TIMESTAMP ou DATETIME |
| TIMESTAMP | TIMESTAMP |
Valores TIMESTAMP, DATETIME e DATE e textos como 2026-01-15 10:00:00 ou 2026-01-15T10:00:00-08:00. Um valor sem fuso horário é lido como UTC. Uma data se torna meia-noite UTC. |
Outros valores, como uma época Unix (1768471200) |
- Um valor que não pode ser convertido não causa falha na execução. Ele é importado
como
NULL, e o Connections não o informa. Portanto, verifique a tabela de destino após a primeira execução. - Escolha o tipo que se ajusta aos seus dados. Para uma origem do BigQuery, escolha
o tipo que corresponde à coluna de origem: STRING para
STRING, INTEGER paraINT64, DOUBLE paraFLOAT64, DATE paraDATEe TIMESTAMP paraTIMESTAMP. Esses valores são importados sem alterações. Para uma origem do Cloud Storage, cada valor CSV é um texto: escolha o tipo dos valores na coluna, como INTEGER para42ou DATE para2026-01-15. Se uma coluna sair comoNULLem todas as linhas, escolha STRING ou converta os valores nos dados de origem primeiro. - Alguns tipos do BigQuery não podem ser mapeados. Se você mapear uma coluna
ARRAY,STRUCT,JSONouGEOGRAPHY, não será possível salvar a conexão. - Cada execução substitui toda a tabela de destino. Ele não adiciona ao final. Se a origem não tiver linhas, o destino ficará vazio. Não use a tabela de origem ou uma tabela com dados que você precisa manter como destino.
Conexões movidas
As transformações ainda não estão disponíveis na experiência atualizada de conexões: não é possível adicionar uma a um campo, e os mapeamentos de campo não as mostram. Uma conexão que foi movida para a experiência atualizada de conexões ainda mantém as transformações dos campos, como o hash de computação (hash SHA-256).
- Em uma conexão de dados próprios, um campo com uma transformação recebe o valor que a transformação produz, em vez da conversão de Tipo, e não é possível mudar o Tipo. Em uma conexão da UPDM, as regras da UPDM ainda se aplicam a esse valor.
- Um campo UPDM que usava hash de computação ainda é criptografado pelo Connections. Mantenha os valores de origem sem hash, mas formatados conforme descrito em Formatar dados para entrada: um valor de hash que já tem hash recebe hash novamente e não pode corresponder. Para gerar hash dos valores por conta própria, remova o mapeamento de campo e adicione-o novamente.
Somente estas transformações são movidas:
- Calcule o hash com SHA-256 (Base64 ou hexadecimal), exceto em um UPDM
user_id,countryouzip_code, que precisa permanecer em texto simples. - Formatação em letras minúsculas ou maiúsculas.
- Conversão para uma string.
- Análise de carimbo de data/hora sem um fuso horário padrão em até 10 campos de uma conexão.
- Dois dos três primeiros em uma linha, como formatação em minúsculas e, em seguida, computação de hash.
Uma transformação só é movida se o que ela produz se encaixa no campo. Para duas em uma linha, o que a segunda produz conta: a formatação em minúsculas e, em seguida, o hash de computação se encaixa em
email, mas o hash de computação e, em seguida, a formatação em minúsculas não.- Em uma conexão UPDM, o hash de computação se encaixa em
email,phone,first_nameelast_name. A formatação em minúsculas ou maiúsculas e a conversão em uma string se encaixam emuser_id,countryezip_code. A análise de carimbo de data/hora não se encaixa em nenhum campo. - Em uma conexão de dados próprios, o hash de computação se ajusta a uma coluna STRING ou HASH. A formatação em minúsculas ou maiúsculas e a conversão em uma string se encaixam em uma coluna STRING. A análise de carimbo de data/hora se ajusta a uma coluna TIMESTAMP.
Uma conexão com qualquer outra transformação, como mesclar ou dividir campos, ou com uma transformação que não se encaixa no campo, não é movida.
- Calcule o hash com SHA-256 (Base64 ou hexadecimal), exceto em um UPDM
Requisitos de coluna CSV do Cloud Storage
- Inclua uma linha de cabeçalho. A primeira linha é ignorada, e os nomes das colunas não são usados.
- O arquivo precisa conter exatamente as colunas de origem mapeadas, nem mais nem menos. Colunas extras causam falha na execução.
- Dados próprios: as colunas precisam estar na mesma ordem que os mapeamentos de campo.
- Correspondência de dados fornecidos pelo usuário: as colunas precisam estar nesta ordem, mantendo apenas os campos que você mapear:
user_id,email,phone,first_name,last_name,country,zip_code. A ordem das linhas de mapeamento não importa. - Uma ordem de coluna diferente não é detectada: os valores são carregados nos campos errados (ou as taxas de correspondência caem) sem um erro.
Fontes de dados compatíveis e limites de conexão
- Fontes de dados: apenas as fontes do BigQuery e do Cloud Storage são compatíveis.
- Nomes de tabelas do BigQuery: as tabelas de origem e destino do BigQuery precisam do
nome completo de
project.dataset.table. - Caminhos de arquivo do Cloud Storage: forneça um único URI de arquivo (como
gs://bucket/path/file.csv). Caminhos curinga com*ou?não são compatíveis. - Nomes de conexão: cada conexão em uma conta precisa ter um nome exclusivo.
Formatar dados para entrada
Seus dados precisam seguir estes requisitos de formatação para serem correspondidos corretamente:
- Onde indicado nas descrições dos campos de entrada a seguir, você precisa fazer upload usando o hash SHA256.
- O UPDM é compatível com a codificação Base64. Consulte TO_BASE64.
- Os campos de entrada precisam ser formatados como strings. Por exemplo, se você estiver usando a
função hash SHA256 do BigQuery,
use a seguinte transformação:
TO_BASE64(SHA256(user_data)).
ID do usuário
- Tipo de dados:
BYTES - Hashing: nenhum
- Remova os espaços em branco à esquerda e à direita.
- Insira todos os caracteres em letras minúsculas.
- Inclua o nome de domínio de todos os endereços de e-mail (por exemplo: gmail.com ou hotmail.com).
- Remova os acentos. Por exemplo, mude è, é, ê ou ë para e.
- Remover todos os pontos (.) que antecedem o nome de domínio nos endereços de e-mail
gmail.comegooglemail.com - Hashing: SHA256 codificado em Base64
Válido até: TO_BASE64(SHA256("jeffersonloveshiking@gmail.com"))
Inválido: TO_BASE64(SHA256("JéffersonLôvesHiking@gmail.com"))
Telefone
- Remover espaços em branco
- Use o formato E.164. Por exemplo, para os EUA: +14155552671; para o Reino Unido: +442071838750.
- Remova todos os caracteres especiais, exceto "+" antes do código do país
- Hashing: SHA256 codificado em Base64
Válido até: TO_BASE64(SHA256("+18005550101"))
Inválido: TO_BASE64(SHA256("(800) 555-0101"))
Nome
- Remover espaços em branco
- Insira todos os caracteres em letras minúsculas.
- Remova todos os prefixos, por exemplo, Sra., Sr., Sra., Dr.
- Não remova acentos, como è, é, ê ou ë.
- Hashing: SHA256 codificado em Base64
Válido até: TO_BASE64(SHA256("daní"))
Inválido: TO_BASE64(SHA256("Daní"))
Sobrenome
- Remover espaços em branco
- Insira todos os caracteres em letras minúsculas.
- Remova todos os sufixos, por exemplo, Jr., Sr., 2nd, 3rd, II, III, PHD, MD
- Não remova acentos, como è, é, ê ou ë.
- Hashing: SHA256 codificado em Base64
Válido até: TO_BASE64(SHA256("délacruz"))
Inválido: TO_BASE64(SHA256("dé la Cruz, Jr."))
País
- Inclua o código do país mesmo que todos os dados do cliente sejam do mesmo país.
- Não criptografe os dados do país com hash.
- Use os códigos de país ISO 3166-1 alfa-2.
- Hashing: nenhum
Válido até: US
Inválido: United States of America ou USA
CEP
- Não gere hash dos dados de CEP.
- São permitidos CEPs e códigos postais dos EUA e internacionais.
- Use apenas letras de A a Z, dígitos, espaços e hifens, com até 20 caracteres
- Para os EUA:
- São permitidos códigos de cinco dígitos, por exemplo, 94043.
- Também aceitamos 5 dígitos seguidos por uma extensão de 4 dígitos, como 94043-1351 ou 940431351.
- Para todos os outros países:
- Não é necessário converter para letras minúsculas nem remover espaços e hifens.
- Não inclua as extensões dos códigos postais.
- Hashing: nenhum
Validação de hash e codificação de dados
Use os seguintes scripts de validação de hash para garantir que seus dados estejam formatados corretamente.
JavaScript
/**
* @fileoverview Provides the hashing algorithm, as well as some valid hashes of
* sample data for testing.
*/
async function hash(token) {
// Removes leading or trailing spaces and converts all characters to lowercase.
const formattedToken = token.trim().toLowerCase();
// Hashes the formatted string using the SHA-256 hashing algorithm.
const hashBuffer = await crypto.subtle.digest(
'SHA-256', (new TextEncoder()).encode(formattedToken));
// Converts the hash buffer to a base64-encoded string and returns it.
const base64Str = btoa(String.fromCharCode(...new Uint8Array(hashBuffer)));
return base64Str;
}
function main() {
// Expected hash for test@gmail.com:
// h5JGBrQTGorO7q6IaFMfu5cSqqB6XTp1aybOD11spnQ=
hash('test@gmail.com').then(result => console.log(result));
// Expected hash for +18005551212:
// YdkRG+0+bZz8G8O1yzWkAmh8TxVGvuBhor1ET73WTEQ=
hash('+18005551212').then(result => console.log(result));
// Expected hash for John: ltljLzY1ZMwwMlIUCc8iqFLyAy7sCZ7VlnwNAAzsYHo=
hash('John').then(result => console.log(result));
// Expected hash for Doe: eZ75KhGvkY4/t0HfQpNPO1aO0tk6wd908bjUGieTKm8=
hash('Doe').then(result => console.log(result));
}
main()
Python
"""Provides the hashing algorithm, as well as some valid hashes of sample data for testing.
Supports: Python 2, Python 3
Sample hashes:
- Email 'test@gmail.com': h5JGBrQTGorO7q6IaFMfu5cSqqB6XTp1aybOD11spnQ=
- Phone '+18005551212': YdkRG+0+bZz8G8O1yzWkAmh8TxVGvuBhor1ET73WTEQ=
- First name 'John': ltljLzY1ZMwwMlIUCc8iqFLyAy7sCZ7VlnwNAAzsYHo=
- Last name 'Doe': eZ75KhGvkY4/t0HfQpNPO1aO0tk6wd908bjUGieTKm8=
"""
import base64
import hashlib
def hash(token):
# Generates a base64-encoded SHA-256 hash of a normalized input string.
return base64.b64encode(
hashlib.sha256(
token.strip().lower().encode('utf-8')).digest()).decode('utf-8')
def print_hash(token, expected=None):
# Computes and displays the hash of a token, with optional validation.
hashed = hash(token)
if expected is not None and hashed != expected:
print(
'ERROR: Incorrect hash for token "{}". Expected "{}", got "{}"'.format(
token, expected, hashed))
return
print('Hash: "{}"\t(Token: {})'.format(hashed, token))
def main():
# Tests the hash function with sample tokens and expected results.
print_hash(
'test@gmail.com', expected='h5JGBrQTGorO7q6IaFMfu5cSqqB6XTp1aybOD11spnQ=')
print_hash(
'+18005551212', expected='YdkRG+0+bZz8G8O1yzWkAmh8TxVGvuBhor1ET73WTEQ=')
print_hash('John', expected='ltljLzY1ZMwwMlIUCc8iqFLyAy7sCZ7VlnwNAAzsYHo=')
print_hash('Doe', expected='eZ75KhGvkY4/t0HfQpNPO1aO0tk6wd908bjUGieTKm8=')
if __name__ == '__main__':
main()
Go
/*
Provides the hashing algorithm, as well as some valid hashes of sample data for testing.
Sample hashes:
- Email 'test@gmail.com': h5JGBrQTGorO7q6IaFMfu5cSqqB6XTp1aybOD11spnQ=
- Phone '+18005551212': YdkRG+0+bZz8G8O1yzWkAmh8TxVGvuBhor1ET73WTEQ=
- First name 'John': ltljLzY1ZMwwMlIUCc8iqFLyAy7sCZ7VlnwNAAzsYHo=
- Last name 'Doe': eZ75KhGvkY4/t0HfQpNPO1aO0tk6wd908bjUGieTKm8=
*/
package main
import (
"crypto/sha256"
"encoding/base64"
"fmt"
"strings"
)
// Hash hashes an email, phone, first name, or last name into the correct format.
func Hash(token string) string {
formatted := strings.TrimSpace(strings.ToLower(token))
hashed := sha256.Sum256([]byte(formatted))
encoded := base64.StdEncoding.EncodeToString(hashed[:])
return encoded
}
// PrintHash prints the hash for a token.
func PrintHash(token string) {
fmt.Printf("Hash: \"%s\"\t(Token: %s)\n", Hash(token), token)
}
func main() {
PrintHash("test@gmail.com")
PrintHash("+18005551212")
PrintHash("John")
PrintHash("Doe")
}
Java
package updm.hashing;
import static java.nio.charset.StandardCharsets.UTF_8;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;
/**
* Example of the hashing algorithm.
*
* <p>Sample hashes:
*
* <ul>
* <li>Email 'test@gmail.com': h5JGBrQTGorO7q6IaFMfu5cSqqB6XTp1aybOD11spnQ=
* <li>Phone '+18005551212': YdkRG+0+bZz8G8O1yzWkAmh8TxVGvuBhor1ET73WTEQ=
* <li>First name 'John': ltljLzY1ZMwwMlIUCc8iqFLyAy7sCZ7VlnwNAAzsYHo=
* <li>Last name 'Doe': eZ75KhGvkY4/t0HfQpNPO1aO0tk6wd908bjUGieTKm8=
* </ul>
*/
public final class HashExample {
private HashExample() {}
public static String hash(String token) {
// Normalizes and hashes the input token using SHA-256 and Base64 encoding.
String formattedToken = token.toLowerCase().strip();
byte[] hash;
try {
hash = MessageDigest.getInstance("SHA-256").digest(formattedToken.getBytes(UTF_8));
} catch (NoSuchAlgorithmException e) {
throw new IllegalStateException("SHA-256 not supported", e);
}
return Base64.getEncoder().encodeToString(hash);
}
public static void printHash(String token) {
// Calculates and prints the hash for the given token.
System.out.printf("Hash: \"%s\"\t(Token: %s)\n", hash(token), token);
}
public static void main(String[] args) {
// Executes hash calculations and prints results for sample tokens.
printHash("test@gmail.com");
printHash("+18005551212");
printHash("John");
printHash("Doe");
}
}
SQL
/*
Provides the hashing algorithm, as well as some valid hashes of sample data for testing.
The following code uses Google Standard SQL and can be run on BigQuery to generate match tables from unhashed data.
Sample hashes:
- Email 'test@gmail.com': h5JGBrQTGorO7q6IaFMfu5cSqqB6XTp1aybOD11spnQ=
- Phone '+18005551212': YdkRG+0+bZz8G8O1yzWkAmh8TxVGvuBhor1ET73WTEQ=
- First name 'John': ltljLzY1ZMwwMlIUCc8iqFLyAy7sCZ7VlnwNAAzsYHo=
- Last name 'Doe': eZ75KhGvkY4/t0HfQpNPO1aO0tk6wd908bjUGieTKm8=
The unhashed input table schema is assumed to be:
- Column name: UserID, Type: String
- Column name: Email, Type: String
- Column name: Phone, Type: String
- Column name: FirstName, Type: String
- Column name: LastName, Type: String
- Column name: PostalCode, Type: String
- Column name: CountryCode, Type: String
*/
-- Creates a new table with Base64-encoded SHA-256 hashes of specified columns.
CREATE TABLE `your_project_name.your_dataset_name.output_hashed_table_name`
AS
SELECT
UserID,
TO_BASE64(SHA256(LOWER(Email))) AS Email,
TO_BASE64(SHA256(Phone)) AS Phone,
TO_BASE64(SHA256(LOWER(FirstName))) AS FirstName,
TO_BASE64(SHA256(LOWER(LastName))) AS LastName,
PostalCode,
CountryCode,
FROM
`your_project_name.your_dataset_name.input_unhashed_table_name`;
Combinar chaves
Algumas combinações de dados fornecidos pelo usuário são mais fortes do que outras. Confira a seguir uma lista de diferentes combinações de dados fornecidos pelo usuário, classificadas por força relativa. Se você usar um endereço, inclua: nome, sobrenome, país e CEP.
- E-mail, telefone, endereço (mais forte)
- Telefone, endereço
- E-mail, endereço
- E-mail, telefone
- Endereço
- Telefone
- E-mail (mais fraco)
Criar uma tabela de correspondência
- Clique em add Criar > Consulta.
Copie o modelo de consulta Geração de tabela de correspondências de nuvem privada e cole-o no editor de consultas. Opcional: use o modelo Geração de tabela de correspondências de nuvem privada (com hash) se os dados ainda não tiverem hash.
/* Private cloud match table generation Create a new match table using your first party data with this template. Parameters: Manually remove all the parameters tagged with @ prefix and replace them with column names from your first party table: * @user_id * @email * @phone * @first_name * @last_name * @country_code * @postal_code And your BigQuery table information: * @my_project: Your BigQuery project where the first party table is. * @my_dataset: Your dataset where the first party table is. * @my_first_party_table: Your first party table. */ CREATE OR REPLACE TABLE adh.updm_match_table AS ( SELECT CAST(@user_id AS BYTES) AS user_id, @email AS email, @phone AS phone, @first_name AS first_name, @last_name AS last_name, @country_code AS country, @postal_code AS zip_code FROM `@my_project.@my_dataset.@my_first_party_table` );/* Private cloud match table generation (with hashing) Create a new match table using your first party data with this template. Parameters: Manually remove all the parameters tagged with @ prefix and replace them with column names from your first party table: * @user_id * @email * @phone * @first_name * @last_name * @country_code * @postal_code And your BigQuery table information: * @my_project : Your BigQuery project where the first party table is. * @my_dataset : Your dataset where the first party table is. * @my_first_party_table : Your first party table. */ CREATE OR REPLACE TABLE adh.updm_match_table AS ( SELECT CAST(@user_id AS BYTES) AS user_id, TO_BASE64(SHA256(LOWER(@email))) AS email, TO_BASE64(SHA256(@phone)) AS phone, TO_BASE64(SHA256(LOWER(@first_name))) AS first_name, TO_BASE64(SHA256(LOWER(@last_name))) AS last_name, @country_code AS country, @postal_code AS zip_code FROM `@my_project.@my_dataset.@my_first_party_table` );Substitua os nomes dos parâmetros pelos nomes das colunas para fornecer o alias adequado.
Clique em Salvar.
Clique em Executar. É necessário executar manualmente essa consulta para atualizar a tabela de correspondência. Cada execução vai substituir a tabela de correspondência atual.
Migrar conexões atuais
As conexões atuais na guia Conexões estão sendo movidas para uma experiência de conexões atualizada, integrada diretamente ao Ads Data Hub. As conexões atualizadas
leem origens e gravam destinos usando a conta de serviço mostrada em
Configurações > Detalhes > Conta de serviço (geralmente
service-<number>@gcp-sa-adsdatahub.iam.gserviceaccount.com) em vez das
contas de serviço legadas do Data Fusion, do Dataproc e do UPDM.
Conclua estas ações necessárias antes que suas conexões sejam movidas:
- Conceder permissões de conta de serviço: conceda à conta de serviço mostrada em
Configurações > Detalhes > Conta de serviço (geralmente
service-<number>@gcp-sa-adsdatahub.iam.gserviceaccount.com) os papéis de origem e destino necessários (roles/bigquery.dataViewer,roles/storage.objectViewereroles/bigquery.dataEditorem conjuntos de dados de destino não padrão). As conexões com origens ilegíveis, excluídas ou alteradas ainda podem ser movidas (especialmente as origens do Cloud Storage, que não são validadas no momento da movimentação), mas as execuções vão falhar até que você conceda acesso ou corrija a origem. Converter conexões incompatíveis: as conexões com as seguintes configurações não serão migradas. Converta-as em conexões compatíveis do BigQuery ou do Cloud Storage:
- Outras fontes de dados (Amazon S3, Snowflake, MySQL, PostgreSQL, Amazon Redshift, sFTP ou Salesforce): prepare os dados no BigQuery ou no Cloud Storage primeiro e, em seguida, crie uma conexão com o BigQuery ou o Cloud Storage.
- Mapeamentos de campo ou tipos de dados incompatíveis: atualize ou recrie a conexão para atender aos requisitos de campo e tipo de dados.
- Transformações incompatíveis: somente as transformações listadas em Conexões movidas são movidas. Remova qualquer outra transformação, como mesclar ou dividir campos, e faça esse trabalho nos dados de origem.
- Caminhos de caracteres curinga do Cloud Storage (
*ou?): substitua o URI de caractere curinga por um único URI de arquivo ou carregue os arquivos no BigQuery primeiro. - Nomes já usados no Ads Data Hub: renomeie a conexão se uma consulta ou uma conexão criada na experiência atualizada de Conexões já tiver o mesmo nome na sua conta.
As conexões atuais que compartilham um nome ainda são migradas: a mais antiga mantém o nome, e as outras recebem um sufixo, como
(2)ou(3).Exclua conexões não utilizadas: exclua conexões obsoletas que não são mais necessárias.
Dados de correspondência de consultas
Consultar as tabelas de correspondência
Quando as tabelas de correspondências tiverem dados suficientes para atender às verificações de privacidade, você poderá fazer consultas nelas.
A tabela original de dados próprios (1PD) é representada por my_data.
Isso inclui informações de identificação pessoal (PII) e dados sem PII.
O uso da tabela original pode melhorar seus relatórios com mais insights, já que ela
representa todos os dados próprios no escopo, em comparação com uma tabela de correspondências.
Cada tabela no esquema do Ads Data Hub que contém um campo user_id é acompanhada por uma tabela de correspondência. Por exemplo, na tabela adh.google_ads_impressions, o Ads Data Hub gera uma tabela de correspondências chamada adh.google_ads_impressions_updm, que inclui os IDs dos usuários.
Tabelas de correspondências separadas são criadas para tabelas de rede isoladas por política. Por exemplo, na tabela adh.google_ads_impressions_policy_isolated_network, o Ads Data Hub gera uma tabela de correspondências chamada adh.google_ads_impressions_policy_isolated_network_updm, que contém seus IDs de usuários.
Elas têm um subconjunto dos usuários disponíveis nas tabelas originais, com uma correspondência em user_id. Por exemplo, se a tabela original tiver dados do Usuário A e do Usuário B, mas só o Usuário A for correspondido, o Usuário B não vai estar na tabela de correspondências.
As tabelas de correspondências contêm uma coluna extra chamada customer_data_user_id, que armazena o identificador de usuário como BYTES.
É importante considerar o tipo do campo na hora de criar suas consultas. Os operadores de comparação do SQL esperam que os literais comparados sejam do mesmo tipo. Dependendo de como o user_id é armazenado na sua tabela de dados próprios, é necessário codificar os valores nela antes de fazer a correspondência dos dados.
É necessário transmitir a chave de mesclagem em BYTES para encontrar correspondências:
JOIN ON
adh.google_ads_impressions_updm.customer_data_user_id = CAST(my_data.user_id AS BYTES)
Além disso, as comparações de strings no SQL consideram maiúsculas e minúsculas. Então, pode ser necessário codificar as strings em ambos os lados da comparação.
Amostras de consultas
Contar usuários correspondentes
Essa consulta conta o número de usuários correspondentes na tabela de impressões de anúncio do Google Ads.
/* Count matched users in Google Ads impressions table */
SELECT COUNT(DISTINCT user_id)
FROM adh.google_ads_impressions_updm
Calcular a taxa de correspondência
Nem todos os usuários estão qualificados para correspondência. Por exemplo, usuários desconectados,
crianças e usuários que não consentiram não são correspondidos pelo UPDM. Use o campo is_updm_eligible para calcular taxas de correspondência mais precisas da UPDM. O campo is_updm_eligible está disponível desde 1º de outubro de 2024. Não é possível usar esse campo para calcular as taxas de correspondência antes dessa data.
/* Calculate the UPDM match rate */
CREATE TEMP TABLE total_events OPTIONS(privacy_checked_export=TRUE) AS
SELECT
customer_id,
COUNT(*) AS n
FROM adh.google_ads_impressions
WHERE is_updm_eligible
GROUP BY 1;
CREATE TEMP TABLE matched_events OPTIONS(privacy_checked_export=TRUE) AS
SELECT
customer_id,
COUNT(*) AS n
FROM adh.google_ads_impressions_updm
GROUP BY 1;
SELECT
customer_id,
SAFE_DIVIDE(matched_events.n, total_events.n) AS match_rate
FROM total_events
LEFT JOIN matched_events
USING (customer_id)
Mesclar dados próprios e dados de anúncios do Google Ads
Esta consulta mostra como combinar dados próprios com dados de anúncios do Google:
/* Join first-party data with Google Ads data. The customer_data_user_id field
contains your ID as BYTES. You need to cast your join key into BYTES for
successful matches. */
SELECT
inventory_type,
COUNT(*) AS impressions
FROM
adh.yt_reserve_impressions_updm AS google_data_imp
LEFT JOIN
`my_data`
ON
google_data_imp.customer_data_user_id = CAST(my_data.user_id AS BYTES)
GROUP BY
inventory_type
Perguntas frequentes sobre o UPDM
Para ver uma lista de perguntas frequentes relacionadas à UPDM, consulte as perguntas frequentes sobre a UPDM.