Correspondência de dados fornecidos pelo usuário

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.

Guia Conexões da correspondência de nuvem privada

Visão geral da correspondência de nuvem privada

Para receber insights valiosos sobre 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 correspondência de nuvem privada 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 seus dados de anúncios aos seus dados próprios. Ao usar dados próprios nas consultas, você oferece uma experiência do cliente mais avançada e consegue lidar melhor com as mudanças no rastreamento de anúncios que atingem 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 são mais resistentes a mudanças do setor do que os dados de terceiros, eles podem fornecer insights mais detalhados, o que pode levar a um maior engajamento do cliente.

Resumo do processo

1. Configuração da ingestão e correspondência de dados
   • 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.
2. 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.
3. 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 consultas regulares no Ads Data Hub. Consulte Consultar dados correspondentes.

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

Alerta: sem a confirmação do consentimento, não é possível usar seus dados próprios no Ads Data Hub. Por exemplo, você não poderia trazer novos dados próprios ou juntar dados próprios atuais com os dados de anúncios vinculados. Dessa forma, todos os casos de uso que utilizam dados próprios, como a correspondência de dados fornecidos pelo usuário e a ativação de público-alvo, ficam indisponíveis. Isso inclui importações programadas desse tipo de dado.

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:

• É preciso 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 integração adicional. Se você pode executar uma consulta de análise, pode executar uma consulta do Private Cloud Match.

Transferir e combinar dados próprios

Observação: as conexões atuais na guia Conexões estão sendo migradas para uma experiência de conexões atualizada. 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 e converta as conexões que usam fontes de dados não compatíveis, caminhos curinga do Cloud Storage ou tipos de campo não compatíveis em conexões compatíveis do BigQuery ou do Cloud Storage antes de serem movidas. Consulte Migrar conexões atuais para mais detalhes.

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 de 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

1. Correspondência de dados fornecidos pelo usuário (UPDM, na sigla em inglês):
   • Mapeie user_id e pelo menos um campo de PII (email, phone ou endereço completo: first_name, last_name, country, zip_code).
   • user_id, country e zip_code: STRING em texto simples (não criptografado). Para uma origem do BigQuery, essas colunas já precisam ser STRING. Outros tipos (por exemplo, INT64) falham quando a conexão é criada. O Connections converte user_id em BYTES na tabela de correspondência. country precisa ser um código ISO 3166-1 alfa-2 de duas letras.
   • email, phone, first_name e last_name: HASH, que já precisam ter hash SHA-256 e codificação Base64 (um valor hexadecimal SHA-256 de 64 caracteres também é aceito). O Connections não gera hash de dados. Os valores de texto simples não são capturados quando a conexão é criada. Cada execução falha com ... must be encoded using TO_BASE64(SHA256(...)).
   • As conexões de correspondência de dados fornecidos pelo usuário não têm uma tabela de destino. Todas as consultas em uma conta e as consultas de UPDM executadas manualmente gravam nos mesmos dados de correspondência, então cada execução substitui a anterior. Uma conexão UPDM por conta é suficiente.
   • Consulte Formatar dados para entrada para ver as regras por campo.
2. Importação de dados próprios:
   • Use apenas os tipos de dados oferecidos na interface: INTEGER, STRING, HASH, DOUBLE, DATE e TIMESTAMP. Outros tipos do BigQuery não são compatíveis.
   • Origem do BigQuery:o tipo mapeado não é aplicado. Cada coluna de destino mantém o tipo da coluna de origem.
   • Origem do Cloud Storage:as colunas são lidas como STRING e convertidas para o tipo mapeado. Os valores que não podem ser transmitidos se tornam NULL sem falhar na execução.
   • Cada execução substitui toda a tabela de destino, sem adicionar 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.

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.
• Importação de 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 do 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 que a correspondência seja feita corretamente:

• Conforme indicado nas descrições dos campos de entrada a seguir, é necessário 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

E-mail

• Remover 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.com e googlemail.com
• Hashing: SHA256 codificado em Base64

Válido até:TO_BASE64(SHA256("[e-mail]"))

Inválido:TO_BASE64(SHA256("JéffersonLô[e-mail]"))

Telefone

• Remover espaços em branco
• Use o formato E.164. Por exemplo, nos EUA: [phone], no Reino Unido: [phone].
• Remova todos os caracteres especiais, exceto o "+" antes do código do país.
• Hashing: SHA256 codificado em Base64

Válido até:TO_BASE64(SHA256("[phone]"))

Inválido:TO_BASE64(SHA256("[phone]"))

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 criptografe os dados do CEP com hash.
• São permitidos CEPs e códigos postais dos EUA e internacionais.
• 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, por exemplo, 94043-1351 ou 940431351.
• Para todos os outros países:
  • Não é necessário formatar (não é preciso usar letras minúsculas nem remover espaços e caracteres especiais)
  • 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 [e-mail]:
    // h5JGBrQTGorO7q6IaFMfu5cSqqB6XTp1aybOD11spnQ=
    hash('[e-mail]').then(result => console.log(result));

    // Expected hash for [phone]:
    // YdkRG+0+bZz8G8O1yzWkAmh8TxVGvuBhor1ET73WTEQ=
    hash('[phone]').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 '[e-mail]': h5JGBrQTGorO7q6IaFMfu5cSqqB6XTp1aybOD11spnQ=
    - Phone '[phone]':   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(
        '[e-mail]', expected='h5JGBrQTGorO7q6IaFMfu5cSqqB6XTp1aybOD11spnQ=')
    print_hash(
        '[phone]', 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 '[e-mail]': h5JGBrQTGorO7q6IaFMfu5cSqqB6XTp1aybOD11spnQ=
    - Phone '[phone]':   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("[e-mail]")
    PrintHash("[phone]")
    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 '[e-mail]': h5JGBrQTGorO7q6IaFMfu5cSqqB6XTp1aybOD11spnQ=
  *   <li>Phone '[phone]': 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("[e-mail]");
    printHash("[phone]");
    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 '[e-mail]': h5JGBrQTGorO7q6IaFMfu5cSqqB6XTp1aybOD11spnQ=
    - Phone '[phone]':   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 eficientes 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.

1. E-mail, telefone, endereço (mais forte)
2. Telefone, endereço
3. E-mail, endereço
4. E-mail, telefone
5. Endereço
6. Telefone
7. E-mail (mais fraco)

Criar uma tabela de correspondência

1. Clique em add Criar > Consulta.

2. 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`
   );
   

3. Substitua os nomes dos parâmetros pelos nomes das colunas para fornecer o alias adequado.

4. Clique em Salvar.

5. 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 transferidas para uma experiência atualizada integrada diretamente ao Ads Data Hub. As conexões atualizadas leem fontes 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 de mover as conexões:

1. 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.objectViewer e roles/bigquery.dataEditor em conjuntos de dados de destino não padrão). As conexões com fontes ilegíveis, excluídas ou alteradas ainda podem ser movidas (especialmente as fontes do Cloud Storage, que não são validadas no momento da movimentação), mas as execuções falham até que você conceda acesso ou corrija a fonte.
2. Converter conexões não compatíveis:as conexões com as seguintes configurações não serão migradas. Converta-as em conexões compatíveis com o BigQuery ou o 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.
   • 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 de conexão duplicados:renomeie ou exclua conexões duplicadas para que cada conexão na conta tenha um nome exclusivo.
3. Excluir conexões não utilizadas:exclua conexões obsoletas que não são mais necessárias.

Dados correspondentes à consulta

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. Usar a 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 dos usuários.

Aviso: devido às regulamentações da UE, o UPDM não está mais disponível para tabelas que não são de rede isoladas por política, como adh.google_ads_impressions_policy_isolated_youtube. Para continuar executando essas consultas, remova _policy_isolated_youtube para limitar apenas aos usuários que deram consentimento.

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.

Observação: as comparações entre bytes e strings codificam bytes em Base64 de forma implícita.

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 a 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

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 Perguntas frequentes sobre a UPDM.