Сопоставление данных, предоставленных пользователями

Сопоставление данных, предоставляемых пользователями (UPDM), объединяет данные, собранные вами о пользователе, например, информацию с ваших веб-сайтов, приложений или физических магазинов, с данными о действиях этого пользователя, вошедшего в систему, во всех данных Google по рекламе , включая данные, принадлежащие и управляемые Google. Сюда входят данные, приобретенные через продукты Google Marketing Platform (GMP), например, YouTube, приобретенные через Display & Video 360. Другие продукты GMP, не принадлежащие и не управляемые Google, не поддерживаются.

Чтобы соответствовать критериям сопоставления предоставленных пользователем данных, рекламное событие должно быть связано с зарегистрированным пользователем в данных рекламы Google.

В этом документе описывается функция сопоставления данных, предоставляемая пользователем, а также содержатся рекомендации по настройке и использованию.

Обзор вкладки «Подключения»

Получение ценной рекламной информации часто требует объединения данных из нескольких источников. Разработка собственного решения этой проблемы с конвейером данных требует значительных временных и инженерных затрат. Страница «Подключения» в Ads Data Hub оптимизирует этот процесс, предоставляя пошаговый интерфейс для импорта, преобразования и сопоставления рекламных данных в BigQuery, чтобы вы могли использовать их в запросах Ads Data Hub или любого другого продукта, считывающего данные из BigQuery. Добавление в запросы собственных данных может обеспечить более качественное взаимодействие с клиентами и более устойчиво к изменениям в системе отслеживания рекламы в отрасли.

Страница «Подключения» содержит инструменты, позволяющие шифровать и обмениваться персональными данными (PII) с партнёрами с учётом конфиденциальности. После выбора столбцов, содержащих PII, Ads Data Hub шифрует данные, гарантируя, что ваши данные первой стороны могут быть экспортированы или прочитаны только теми, у кого есть на это разрешение. Определение того, какие данные первой стороны необходимы для вашего сценария использования для измерения или активации, может быть сложным, поэтому Ads Data Hub предоставляет полный список предопределённых сценариев использования, а затем проведёт вас через весь процесс извлечения, преобразования и загрузки данных. Хотя Ads Data Hub может создавать различные типы подключений, в этом документе предполагается, что вы используете страницу «Подключения» для сопоставления данных, предоставленных пользователями.

Поддерживаемые собственные источники данных

Вы можете импортировать данные из следующих источников данных:

  • BigQuery
  • Облачное хранилище
  • Безопасный FTP (sFTP)
  • Снежинка
  • MySQL
  • PostgreSQL
  • Amazon Redshift
  • Амазон S3

Поскольку сопоставление данных, предоставленных пользователями, доступно только для инвентаря, принадлежащего и управляемого Google, для зарегистрированных пользователей, на него не повлияет предстоящее прекращение поддержки сторонних файлов cookie . Поскольку эти данные более устойчивы к изменениям в отрасли, чем сторонние данные, они могут предоставить более содержательную аналитику, что может привести к более активному участию клиентов.

Изучите терминологию

  • Подключение к данным, предоставляемое пользователем: настройте подключение к данным, предоставляемое пользователем, для импорта и сопоставления ваших данных, планирования импорта данных, преобразования данных и сопоставления данных ваших рекламных объявлений с использованием идентификатора пользователя. Событие объявления должно быть связано с зарегистрированным пользователем в данных Google Ad. Требуется несколько проектов Google Cloud.
  • Подключение к данным первой стороны: настройте подключение к данным первой стороны как инструмент подготовки данных, чтобы планировать импорт и преобразование данных без использования расширенных функций UPDM. Для такого подключения требуется только один проект Google Cloud.
  • Источник данных: подключенный продукт, импортированный файл или сторонняя интеграция, например, BigQuery.
  • Назначение: вариант использования; обычно продукт или функция продукта Google, где активируются импортированные данные, например, сопоставление предоставленных пользователем данных Ads Data Hub.
  • Проект администратора: проект Google Cloud, содержащий ваши фирменные рекламные данные в необработанном формате.
  • Выходной набор данных: набор данных BigQuery, в который записывается информация из Ads Data Hub. По умолчанию это набор данных в вашем проекте администратора. Чтобы изменить его на другой проект Google Cloud, см. раздел «Настройка сервисных аккаунтов» .

Краткое описание процесса

  1. Настройка приема и сопоставления данных
  2. Прием и сопоставление данных из первых рук
    • Вы форматируете и загружаете собственные данные в свой набор данных BigQuery. Для простейшей настройки используйте проект администратора . Однако вы можете использовать любой принадлежащий вам набор данных BigQuery.
    • Вы инициируете запрос на сопоставление данных, создавая подключение и устанавливая расписание импорта.
    • Google объединяет данные вашего проекта и данные Google, содержащие идентификатор пользователя Google и хешированные предоставленные пользователями данные, для создания и обновления таблиц соответствий.
    • См. раздел «Прием собственных данных»
  3. Текущие запросы в Ads Data Hub на основе сопоставленных данных

Узнайте о требованиях конфиденциальности

Сбор данных о клиентах

При использовании сопоставления данных, предоставленных пользователями, необходимо загрузить собственные данные. Это может быть информация, собранная вами на ваших веб-сайтах, в приложениях, в обычных магазинах, а также любая информация, которой клиент поделился с вами напрямую.

Вы должны:

  • Убедитесь, что ваша политика конфиденциальности раскрывает информацию о том, что вы передаете данные клиентов третьим лицам для оказания услуг от вашего имени, и что вы получаете согласие на такую ​​передачу в случаях, когда это требуется по закону.
  • Используйте только одобренный API или интерфейс Google для загрузки данных клиентов.
  • Соблюдайте все применимые законы и правила , включая любые кодексы саморегулирования или отраслевые кодексы, которые могут применяться.

Подтверждение согласия первой стороны

Чтобы использовать свои собственные данные в Ads Data Hub, вы должны подтвердить, что получили надлежащее согласие на передачу данных от конечных пользователей из ЕЭЗ в Google в соответствии с Политикой согласия пользователей из ЕС и Политикой Ads Data Hub . Это требование применяется к каждой учётной записи Ads Data Hub и должно обновляться при каждой загрузке новых собственных данных. Любой пользователь может дать такое согласие от имени всей учётной записи.

Обратите внимание, что к запросам UPDM применяются те же правила запросов к сервисам Google, что и к аналитическим запросам. Например, при создании таблицы соответствий невозможно выполнять кросс-сервисные запросы по пользователям в ЕЭЗ.

Чтобы узнать, как подтвердить согласие в Ads Data Hub, ознакомьтесь с требованиями к согласию для Европейской экономической зоны .

Размер данных

Для защиты конфиденциальности конечного пользователя сопоставление предоставленных пользователем данных обеспечивает соблюдение следующих требований к размеру ваших данных:

  • Вам необходимо загрузить не менее 1000 записей в свой список пользователей.
  • Каждое успешное обновление таблицы соответствий должно включать минимальное количество новых сопоставленных пользователей. Это поведение аналогично проверке различий .
  • Ваш список не должен превышать максимальное количество записей. Чтобы узнать о максимальном лимите данных, обратитесь к представителю Google.

Настройте прием данных

Прежде чем начать, вам необходимо настроить учётную запись Ads Data Hub для создания подключений к данным, которые позволят вам организовать процесс сопоставления данных. Эти действия необходимо выполнить только один раз.

На странице Подключения нажмите Начать настройку , чтобы открыть мастер настройки учетной записи на этапе включения UPDM.

Перейти к соединениям

Какие разрешения предоставляются для BigQuery и Cloud Storage?

Если вы настраиваете UPDM для использования с BigQuery или Cloud Storage, воспользуйтесь этой ссылкой, чтобы понять разрешения, предоставляемые учетным записям службы Ads Data Hub.

BigQuery

Учетная запись службы Datafusion
Цель Учетная запись службы datafusion используется для отображения списка исходных полей в пользовательском интерфейсе Ads Data Hub.
Формат service- some-number @gcp-sa-datafusion.iam.gserviceaccount.com
Требуемый доступ
BigQuery Data Viewer
roles/bigquery.dataViewer
 для определенных наборов данных в проектах «Источник данных» и «Назначение данных»
Storage Admin
roles/storage.admin
 для проекта источника данных или выделенного контейнера хранения
Учетная запись службы Dataproc
Цель Учетная запись службы dataproc отвечает за работу конвейеров данных в фоновом режиме.
Формат some-number -compute@developer.gserviceaccount.com
Требуемый доступ
BigQuery Data Viewer
roles/bigquery.dataViewer
 для определенных наборов данных в проектах «Источник данных» и «Назначение данных»
BigQuery Data Editor
roles/bigquery.dataEditor
 для определенных наборов данных в проекте Destination
BigQuery Job User
roles/bigquery.jobUser
 для проектов «Источник данных» и «Назначение данных»
Storage Admin
roles/storage.admin
 для проектов «Источник данных» и «Назначение» или выделенный контейнер для хранения
Учетная запись службы UPDM
Цель Учетная запись службы UPDM используется для запуска задания по сопоставлению.
Формат service- some-number @gcp-sa-adsdataconnector.iam.gserviceaccount.com
Требуемый доступ
BigQuery Data Viewer
roles/bigquery.dataViewer
 для проекта «Пункт назначения»
BigQuery Job User
roles/bigquery.jobUser
 для проекта «Пункт назначения»

Облачное хранилище

Учетная запись службы Datafusion
Цель Учетная запись службы datafusion используется для отображения списка исходных полей в пользовательском интерфейсе Ads Data Hub.
Формат service- some-number @gcp-sa-datafusion.iam.gserviceaccount.com
Требуемый доступ
Storage Object Viewer
roles/storage.objectViewer
 для определенных контейнеров хранения в проекте источника данных
BigQuery Data Viewer
roles/bigquery.dataViewer
 для проекта источника данных или выделенного контейнера хранения
Storage Admin
roles/storage.admin
 для проекта источника данных или выделенного контейнера хранения
Учетная запись службы Dataproc
Цель Учетная запись службы dataproc отвечает за работу конвейеров данных в фоновом режиме.
Формат some-number -compute@developer.gserviceaccount.com
Требуемый доступ
Storage Admin
roles/storage.admin
 для проектов «Источник данных» и «Назначение» или выделенный контейнер для хранения
BigQuery Job User
roles/bigquery.jobUser
 для проекта «Пункт назначения»
Учетная запись службы UPDM
Цель Учетная запись службы UPDM используется для запуска задания по сопоставлению.
Формат service- some-number @gcp-sa-adsdataconnector.iam.gserviceaccount.com
Требуемый доступ
BigQuery Data Viewer
roles/bigquery.dataViewer
 для проекта «Пункт назначения»
BigQuery Job User
roles/bigquery.jobUser
 для проекта «Пункт назначения»

Другие источники данных

Не требуется для других источников данных

Прием и сопоставление собственных данных

Форматировать данные для ввода

Для корректного сопоставления ваши данные должны соответствовать следующим требованиям к форматированию:

  • В полях ввода, указанных ниже, необходимо выполнить загрузку с использованием хеширования SHA256.
  • Поля ввода должны быть отформатированы как строки. Например, если вы используете хеш-функцию BigQuery SHA256 с функцией кодирования Base16 ( TO_HEX ), используйте следующее преобразование: TO_HEX(SHA256(user_data)) .
  • UPDM поддерживает кодировку Base16 и Base64. Необходимо согласовать кодировку ваших собственных данных с декодированием, используемым в запросе Ads Data Hub. При изменении кодировки собственных данных необходимо обновить запрос Ads Data Hub для декодирования с той же базой данных. В следующих примерах используется кодировка Base16.

ID пользователя

  • Обычный текст
  • Хеширование: нет

Электронная почта

  • Удалить начальные и конечные пробелы
  • Все символы строчные
  • Укажите доменное имя для всех адресов электронной почты, например gmail.com или hotmail.co.jp.
  • Удалите акценты — например, измените è, é, ê или ë на e
  • Удалите все точки (.) перед именем домена в адресах электронной почты gmail.com и googlemail.com
  • Хеширование: SHA256, закодированное в Base16

Действительно: TO_HEX(SHA256("jeffersonloveshiking@gmail.com"))

Неверно: TO_HEX(SHA256("JéffersonLôvesHiking@gmail.com"))

Телефон

  • Удалить пробелы
  • Формат в формате E.164 — например, для США: +14155552671, для Великобритании: +442071838750
  • Удалите все специальные символы, кроме «+» перед кодом страны.
  • Хеширование: SHA256, закодированное в Base16

Действительно: TO_HEX(SHA256("+18005550101"))

Недопустимо: TO_HEX(SHA256("(800) 555-0101"))

Имя

  • Удалить пробелы
  • Все символы строчные
  • Удалите все префиксы, например, Mrs., Mr., Ms., Dr.
  • Не удаляйте ударения, например, è, é, ê или ë.
  • Хеширование: SHA256, закодированное в Base16

Допустимо: TO_HEX(SHA256("daní"))

Неверно: TO_HEX(SHA256("Daní"))

Фамилия

  • Удалить пробелы
  • Все символы строчные
  • Удалите все суффиксы, например младший, старший, 2-й, 3-й, II, III, PHD, MD.
  • Не удаляйте ударения, например, è, é, ê или ë.
  • Хеширование: SHA256, закодированное в Base16

Действительно: TO_HEX(SHA256("delacruz"))

Неверно: TO_HEX(SHA256("de la Cruz, Jr."))

Страна

  • Укажите код страны, даже если все данные ваших клиентов относятся к одной и той же стране.
  • Не хешируйте данные о стране
  • Используйте коды стран ISO 3166-1 alpha-2
  • Хеширование: нет

Действительно: US

Недействительно: United States of America или USA

Почтовый индекс

  • Не хешируйте данные почтового индекса
  • Разрешены как американские, так и международные почтовые индексы.
  • Для США:
    • Допускаются 5-значные коды, например, 94043.
    • Также разрешены 5 цифр с последующим 4-значным расширением, например, 94043-1351 или 940431351.
  • Для всех остальных стран:
    • Форматирование не требуется (не нужно переводить буквы в нижний регистр, удалять пробелы и специальные символы)
    • Не указывайте расширения почтовых индексов.
  • Хеширование: нет

Проверка хеша и кодирование данных

Чтобы убедиться, что ваши данные отформатированы правильно, вы можете использовать следующие скрипты проверки хеша.

JavaScript

Base16 

/**
 * @fileoverview Provides the hashing algorithm for User-Provided Data Match, 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 hashArrayBuffer = await crypto.subtle.digest(
      'SHA-256', (new TextEncoder()).encode(formattedToken));
  // Converts the hash buffer to a hexadecimal string.
  return Array.from(new Uint8Array(hashArrayBuffer))
      .map((b) => b.toString(16).padStart(2, '0'))
      .join('');
}

function main() {
  // Expected hash for test@gmail.com:
  // 87924606b4131a8aceeeae8868531fbb9712aaa07a5d3a756b26ce0f5d6ca674
  hash('test@gmail.com').then(result => console.log(result));

  // Expected hash for +18005551212:
  // 61d9111bed3e6d9cfc1bc3b5cb35a402687c4f1546bee061a2bd444fbdd64c44
  hash('+18005551212').then(result => console.log(result));

  // Expected hash for John:
  // 96d9632f363564cc3032521409cf22a852f2032eec099ed5967c0d000cec607a
  hash('John').then(result => console.log(result));

  // Expected hash for Doe:
  // 799ef92a11af918e3fb741df42934f3b568ed2d93ac1df74f1b8d41a27932a6f
  hash('Doe').then(result => console.log(result));
}

main()

Base64 

/**
 * @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()

Питон

Base16 

"""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': 87924606b4131a8aceeeae8868531fbb9712aaa07a5d3a756b26ce0f5d6ca674
  - Phone '+18005551212':   61d9111bed3e6d9cfc1bc3b5cb35a402687c4f1546bee061a2bd444fbdd64c44
  - First name 'John':      96d9632f363564cc3032521409cf22a852f2032eec099ed5967c0d000cec607a
  - Last name 'Doe':        799ef92a11af918e3fb741df42934f3b568ed2d93ac1df74f1b8d41a27932a6f
"""

import base64
import hashlib

def updm_hash(token):
# Generates a SHA-256 hash of the input token after normalization.
  return hashlib.sha256(token.strip().lower().encode('utf-8')).hexdigest()

def print_updm_hash(token):
# Prints the SHA-256 hash and the original token.
  print('Hash: "{}"\t(Token: {})'.format(updm_hash(token), token))

def main():
# Hashes and prints sample tokens.
  print_updm_hash('test@gmail.com')
  print_updm_hash('+18005551212')
  print_updm_hash('John')
  print_updm_hash('Doe')

if __name__ == '__main__':
  main()

Base64 

"""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()

Идти

Base16 

/*
Provides the hashing algorithm, as well as some valid hashes of sample data for testing.

Sample hashes:

  - Email 'test@gmail.com': 87924606b4131a8aceeeae8868531fbb9712aaa07a5d3a756b26ce0f5d6ca674
  - Phone '+18005551212':   61d9111bed3e6d9cfc1bc3b5cb35a402687c4f1546bee061a2bd444fbdd64c44
  - First name 'John':      96d9632f363564cc3032521409cf22a852f2032eec099ed5967c0d000cec607a
  - Last name 'Doe':        799ef92a11af918e3fb741df42934f3b568ed2d93ac1df74f1b8d41a27932a6f
*/
package main

import (
  "crypto/sha256"
  "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 := fmt.Sprintf("%x", 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")
}

Base64 

/*
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")
}

Ява

Base16 

package updm.hashing;

import static java.nio.charset.StandardCharsets.UTF_8;

import com.google.common.base.Ascii;
import com.google.common.hash.Hashing;

/**
 * Example of the UPDM hashing algorithm using hex-encoded SHA-256.
*
* <p>This uses the Guava Hashing to generate the hash: https://github.com/google/guava
*
* <p>Sample valid hashes:
*
* <ul>
*   <li>Email "test@gmail.com": "87924606b4131a8aceeeae8868531fbb9712aaa07a5d3a756b26ce0f5d6ca674"
*   <li>Phone "+18005551212": "61d9111bed3e6d9cfc1bc3b5cb35a402687c4f1546bee061a2bd444fbdd64c44"
*   <li>First name "John": "96d9632f363564cc3032521409cf22a852f2032eec099ed5967c0d000cec607a"
*   <li>Last name "Doe": "799ef92a11af918e3fb741df42934f3b568ed2d93ac1df74f1b8d41a27932a6f"
* </ul>
*/
public final class HashExample {

  private HashExample() {}

  public static String hash(String token) {
    // Normalizes and hashes the input token.
    String formattedToken = Ascii.toLowerCase(token).strip();
    return Hashing.sha256().hashString(formattedToken, UTF_8).toString();
  }

  public static void printHash(String token) {
    // Calculates and prints the token's hash.
    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");
  }
}

Base64 

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

Base16 

/*
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': 87924606b4131a8aceeeae8868531fbb9712aaa07a5d3a756b26ce0f5d6ca674
  - Phone '+18005551212':   61d9111bed3e6d9cfc1bc3b5cb35a402687c4f1546bee061a2bd444fbdd64c44
  - First name 'John':      96d9632f363564cc3032521409cf22a852f2032eec099ed5967c0d000cec607a
  - Last name 'Doe':        799ef92a11af918e3fb741df42934f3b568ed2d93ac1df74f1b8d41a27932a6f

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 hashed versions of specified columns from the input table.
CREATE TABLE `your_project_name.your_dataset_name.output_hashed_table_name`
AS
SELECT
  UserID,
  TO_HEX(SHA256(LOWER(Email))) AS Email,
  TO_HEX(SHA256(Phone)) AS Phone,
  TO_HEX(SHA256(LOWER(FirstName))) AS FirstName,
  TO_HEX(SHA256(LOWER(LastName))) AS LastName,
  PostalCode,
  CountryCode,
FROM
  `your_project_name.your_dataset_name.input_unhashed_table_name`;

Base64 

/*
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`;

Присоединить ключи

Некоторые комбинации предоставленных пользователями данных надёжнее других. Ниже приведён список различных комбинаций предоставленных пользователями данных, отсортированных по относительной надёжности. Если вы используете адрес, необходимо указать: имя, фамилию, страну и почтовый индекс.

  1. Электронная почта, телефон, адрес (самый надежный)
  2. Телефон, адрес
  3. Адрес электронной почты
  4. Электронная почта, Телефон
  5. Адрес
  6. Телефон
  7. Электронная почта (самая слабая)

Создайте таблицу соответствий

  1. Нажмите Подключения > Создать подключение > Сопоставление предоставленных пользователем данных .
  2. Выберите источник данных, затем нажмите Подключиться .
  3. При необходимости выполните аутентификацию, затем нажмите «Далее» :

    BigQuery

    Нажмите «Применить», чтобы предоставить доступ к BigQuery.

    Облачное хранилище

    Нажмите «Применить», чтобы предоставить доступ к облачному хранилищу.

    MySQL

    Введите местоположение базы данных MySQL, порт, имя пользователя и пароль.

    С3

    Введите секретный ключ доступа Amazon S3.

    PostgreSQL

    Введите местоположение базы данных PostgreSQL, порт, имя пользователя, пароль и базу данных.

    Красное смещение

    Введите местоположение базы данных Redshift, порт, имя пользователя, пароль и базу данных.

    sFTP

    Введите местоположение вашего sFTP-сервера, имя пользователя и пароль.

    Снежинка

    Введите идентификатор вашей учетной записи Snowflake, имя пользователя и пароль.

  4. Настройте источник данных, затем нажмите «Далее» :

    BigQuery

    Выберите таблицу BigQuery для импорта.

    Облачное хранилище

    Введите путь gsutil, например gs://my-bucket/folder/ и выберите форматирование файла.

    Если вы подключаете этот ресурс впервые, появится уведомление. Нажмите «Применить», чтобы предоставить доступ, затем нажмите «Далее». Примечание: у вас должна быть роль с разрешением делегировать storage.buckets.setIamPolicy для соответствующего контейнера.

    MySQL

    Выберите базу данных MySQL и таблицу, которую вы хотите использовать.

    С3

    Введите URI файла, который вы хотите загрузить, относительно адреса хоста.

    PostgreSQL

    Введите схему PostgreSQL и имя таблицы (или представления).

    Красное смещение

    Введите схему Redshift и имя таблицы (или представления). По умолчанию Redshift использует URL-адреса расположения базы данных по следующему шаблону: cluster-identifier.account-number.aws-region.redshift.amazonaws.com region.redshift.amazonaws.com .

    sFTP

    Введите путь и имя файла в / PATH / FILENAME .csv

    Снежинка

    Введите базу данных Snowflake, схему и таблицу (или представление), которые вы хотите использовать.

  5. Выберите набор данных BigQuery, который будет использоваться в качестве промежуточного назначения , и нажмите «Далее» . Это гарантирует правильность форматирования данных.
  6. Необязательно: измените формат данных. Преобразования включают вычисление хэша, форматирование строчных и прописных букв, а также объединение и разделение полей.
    1. Нажмите Действие > > Преобразовать .
    2. В открывшейся панели нажмите «Добавить преобразование» или «Добавить другое преобразование».
    3. Выберите тип преобразования из раскрывающегося меню и введите требования.
    4. Нажмите «Сохранить» .
  7. Выберите хотя бы один ключ соединения и сопоставьте поля, которые вы будете использовать. Ads Data Hub автоматически сопоставит поля с одинаковыми именами, обозначенными как . Внесите необходимые изменения и нажмите «Далее» .
  8. Установите расписание:
    1. Дайте название вашему соединению.
    2. Установите частоту, определяющую, как часто данные будут импортироваться в набор данных, выбранный на предыдущем шаге. Каждый запуск будет перезаписывать данные в целевой таблице.
    3. Укажите, как следует обрабатывать конфликты идентификаторов пользователей. Вы можете сохранить существующее совпадение или перезаписать его новыми данными.
  9. Нажмите «Готово» . Таблицы соответствий обычно готовы к выполнению запросов через 12 часов после создания.

Посмотреть детали подключения

На странице сведений о подключении представлена ​​информация о последних запусках и ошибках данного подключения. Чтобы просмотреть сведения о конкретном подключении:

  1. Нажмите Подключения .
  2. Щелкните имя соединения, чтобы просмотреть подробную информацию.
  3. Теперь вы можете просмотреть сведения о подключении и недавних запусках. Для каждого из них отображаются два возможных типа ошибок: ошибки на уровне подключения (подключение не было установлено) и ошибки на уровне строк (строка не была импортирована).
    1. Статус «Сбой» означает, что подключение не удалось запустить (например, из-за проблемы с правами доступа к учётной записи службы). Щёлкните по статусу ошибки, чтобы узнать, какие ошибки повлияли на подключение.
    2. Статус «Завершено» означает, что подключение выполнено успешно. Однако могут быть ошибки на уровне строк, о чём свидетельствует ненулевое значение в столбце «Строки с ошибками». Щёлкните по значению, чтобы узнать, какие записи не удалось соединить.

Редактировать соединение

Следующие данные могут быть отредактированы:

  • Имя соединения
  • Расписание
  • Таблица назначения
  • Картографирование полей

Редактирование источника данных не поддерживается. Чтобы изменить источник данных, создайте новое подключение и удалите старое.

Чтобы изменить данные подключения:

  1. Нажмите Подключения .
  2. Щелкните имя соединения, которое вы хотите отредактировать.
  3. Отредактируйте данные, которые вы хотите изменить:
    • Имя подключения: Нажмите «Изменить» , введите новое имя, затем нажмите Enter .
    • Расписание: Нажмите «Изменить» , установите новое расписание, затем нажмите «Сохранить» .
    • Таблица назначения: Нажмите «Изменить» , введите новое имя назначения, затем нажмите «Сохранить» .
    • Сопоставление полей: Нажмите , внесите изменения в поля, затем нажмите Save .
  4. Нажмите .

Запрос соответствующих данных

Запросить таблицы соответствий

Когда ваши таблицы соответствий содержат достаточно данных для удовлетворения проверок конфиденциальности, вы готовы выполнять запросы к таблицам.

Исходная таблица для данных первой стороны (1PD) представлена my_data . Она включает как персональные данные (PII), так и данные, не относящиеся к PII. Использование исходной таблицы может улучшить ваши отчёты и сделать их более информативными, поскольку она представляет все данные первой стороны в области охвата, по сравнению с таблицей соответствий.

Каждая таблица в схеме Ads Data Hub, содержащая поле user_id , сопровождается таблицей соответствий. Например, для таблицы adh.google_ads_impressions Ads Data Hub также генерирует таблицу соответствий adh.google_ads_impressions_updm , содержащую ваши идентификаторы пользователей. Отдельные таблицы соответствий создаются для таблиц сетей, изолированных от политик. Например, для таблицы adh.google_ads_impressions_policy_isolated_network Ads Data Hub также генерирует таблицу соответствий adh.google_ads_impressions_policy_isolated_network_updm , содержащую ваши идентификаторы пользователей.

Эти таблицы содержат подмножество пользователей, доступных в исходных таблицах, для которых есть совпадение по user_id . Например, если исходная таблица содержит данные для пользователей A и B, но совпадение обнаружено только для пользователя A, то пользователь B не будет отображаться в таблице соответствий.

Таблицы соответствий содержат дополнительный столбец customer_data_user_id , в котором хранится идентификатор пользователя в виде БАЙТОВ.

При написании запросов важно учитывать тип поля. Операторы сравнения SQL предполагают, что сравниваемые литералы имеют одинаковый тип. В зависимости от того, как хранится user_id в таблице с данными из первой партии, вам может потребоваться кодировать значения в таблице перед сопоставлением данных. Для успешного сопоставления необходимо преобразовать ключ соединения в тип BYTES: 

JOIN ON
  adh.google_ads_impressions_updm.customer_data_user_id = CAST(my_data.user_id AS BYTES)

Кроме того, сравнение строк в SQL чувствительно к регистру букв, поэтому вам может потребоваться кодировать строки с обеих сторон сравнения, чтобы обеспечить их точное сравнение.

Примеры запросов

Количество соответствующих пользователей

Этот запрос подсчитывает количество соответствующих пользователей в таблице показов Google Ads. 

/* Count matched users in Google Ads impressions table */

SELECT COUNT(DISTINCT user_id)
FROM adh.google_ads_impressions_updm

Рассчитать коэффициент соответствия

Не все пользователи могут быть сопоставлены. Например, пользователи, не вошедшие в систему, дети и несогласованные пользователи не сопоставлены через UPDM. Вы можете использовать поле is_updm_eligible для более точного расчета коэффициентов соответствия UPDM. Обратите внимание, что поле is_updm_eligible доступно с 1 октября 2024 года. До этой даты это поле нельзя использовать для расчета коэффициентов соответствия. 

/* 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)

Объедините собственные данные и данные Google Ads

Этот запрос показывает, как объединить собственные данные с данными Google Ads: 

/* 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

Часто задаваемые вопросы по UPDM

Список часто задаваемых вопросов, связанных с UPDM, см. в разделе Часто задаваемые вопросы по UPDM .