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

Функция сопоставления данных, предоставленных пользователями, связывает собранные вами данные о пользователе (данные с ваших сайтов, из приложений или обычных магазинов) с действием входа этого пользователя во всех данных рекламы Google, включая данные, принадлежащие Google и управляемые Google. Это относится и к данным, приобретенным через продукты Google Платформы для маркетинга, например к данным YouTube, приобретенным через Дисплей и Видео 360. Другие продукты GMP, которые не принадлежат Google и не управляются этой компанией, не поддерживаются.

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

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

Общие сведения о сопоставлении в частном облаке

Чтобы получить ценную статистику, часто приходится объединять данные из разных источников. Создание собственного решения для этой проблемы конвейера данных требует значительных затрат времени и инженерных инвестиций. Private Cloud Match в Ads Data Hub упрощает этот процесс, предоставляя шаблон запроса Ads Data Hub для создания таблицы соответствий в BigQuery, которую затем можно использовать в запросах Ads Data Hub для сопоставления данных рекламы с вашими собственными данными. Обогащение запросов собственными данными может повысить удовлетворенность клиентов и устойчивость к отраслевым изменениям в области отслеживания рекламы.

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

Обзор процесса

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

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

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

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

Кроме того, вы должны выполнить следующее:

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

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

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

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

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

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

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

  • В списке пользователей должно быть не менее 1000 записей.

Как настроить добавление данных

Прежде чем начать, убедитесь, что:

  • Ваши собственные данные должны храниться в BigQuery. Если у вас есть периметр VPC-SC, эти собственные данные должны находиться в нем.
  • У сервисного аккаунта Ads Data Hub должен быть доступ с правами чтения к собственным данным.
  • Ваши собственные данные должны быть правильно отформатированы и хешированы. Более подробную информацию вы найдете в следующем разделе.

Других действий для начала работы с Private Cloud Match не требуется. Если вы можете выполнить аналитический запрос, то можете выполнить и запрос Private Cloud Match.

Как добавлять и сопоставлять собственные данные

Разрешения для источника и требования к подключению

В Ads Data Hub Connections используется сервисный аккаунт, указанный в разделе Настройки > Подробности > Сервисный аккаунт (обычно это service-<number>@gcp-sa-adsdatahub.iam.gserviceaccount.com). Назначьте ему следующие роли:

  • Источник BigQuery: roles/bigquery.dataViewer (Наблюдатель данных BigQuery) для исходного набора данных или таблицы.
  • Источник Cloud Storage: roles/storage.objectViewer (Storage Object Viewer) для исходного сегмента или объекта.
  • Целевой сервис для импорта собственных данных: roles/bigquery.dataEditor (Редактор данных BigQuery) для целевого набора данных, если таблица не находится в наборе данных по умолчанию.

Требования к полям и типам данных

Эти правила относятся к связям в обновленном интерфейсе. Они зависят от типа подключения: сопоставление данных, предоставленных пользователями или собственные данные.

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

Сопоставьте столбец user_id и хотя бы один из следующих столбцов: email, phone или полный адрес (first_name, last_name, country и zip_code). Если вы сопоставляете какой-либо столбец адреса, сопоставьте все четыре. В противном случае вы не сможете сохранить связь. Значение в столбце Type (Тип) изменить нельзя. Для столбцов email, phone, first_name и last_name это HASH (Хеш), а для столбцов user_id, country и zip_code – STRING (Строка).

Исходный столбец, который вы сопоставляете с каждым целевым столбцом, должен содержать следующее: Подробнее о том, как форматировать данные для ввода…

Целевой столбец Значение исходного столбца Пример
user_id Ваш идентификатор пользователя в виде обычного текста. customer-1234
email, phone, first_name, last_name Отформатированное значение, хешированное с помощью SHA-256 и закодированное в Base64 (44 символа). Также можно использовать шестнадцатеричную кодировку (64 символа). h5JGBrQTGorO7q6IaFMfu5cSqqB6XTp1aybOD11spnQ=, хеш test@gmail.com
country Двухбуквенный код страны (ISO 3166-1 alpha-2) в виде обычного текста. US
zip_code Почтовый индекс длиной до 20 символов (буквы A–Z, цифры, пробелы и дефисы) в виде обычного текста. 94043
  • Хешируйте значения в источнике. Connections не хеширует email, phone, first_name и last_name, несмотря на то, что для них указан тип HASH. Исключение: если ваше подключение было перенесено в обновленный интерфейс подключений и до переноса для поля использовалось вычисление хеша (столбец хешировался автоматически), то в подключениях это поле по-прежнему хешируется. Не хешируйте исходные значения этого поля, но отформатируйте их. Подробнее о перенесенных связях…
  • В исходной таблице BigQuery используйте столбцы STRING.
    • Значения email, phone, first_name и last_name должны быть равны STRING. Если вы выберете другой тип, например INT64, то не сможете сохранить подключение.
    • user_id также может быть INT64 или BYTES. Если значение BYTES не является текстом в кодировке UTF-8, оно преобразуется в NULL.
    • zip_code также может быть INT64, но INT64 не может содержать ведущий ноль (02134 хранится как 2134), поэтому такой почтовый индекс не может совпадать. Сохраняйте почтовые индексы в формате STRING.
  • Укажите идентификатор пользователя в каждой строке. Все строки с идентификатором пользователя NULL считаются одним пользователем, поэтому совпадение может быть только одно. То же самое относится ко всем строкам с пустым идентификатором пользователя.
  • Идентификатор пользователя станет таким: BYTES. Connections преобразует его в BYTES – тип идентификатора пользователя, указанный в разделе Форматирование данных для ввода. Таким образом, в исходном столбце можно оставить STRING. Например, значение INT64 42 станет b"42". В таблицах соответствий _updm это столбец customer_data_user_id. CAST(my_data.user_id AS BYTES) не работает для идентификатора INT64, поэтому для объединения сначала преобразуйте его в STRING: customer_data_user_id = CAST(CAST(my_data.user_id AS STRING) AS BYTES).
  • Пустые или неправильно отформатированные значения адреса электронной почты, номера телефона или почтового адреса не могут быть сопоставлены, но не приводят к сбою выполнения. Строка по-прежнему может соответствовать другим значениям. Например, адрес электронной почты в виде обычного текста, страна USA или почтовый индекс 94043.1351 не будут сопоставлены. Чтобы сопоставить адрес, в строке должны быть указаны действительные значения во всех четырех столбцах адреса.
  • Если в запросе Cloud Match в частном облаке значение указано в неверном формате, то весь запрос может быть не выполнен. Это относится к случаям, когда вы создаете таблицу соответствия с помощью запроса CREATE OR REPLACE TABLE adh.updm_match_table в Ads Data Hub, а не подключения. Например, если хеш адреса электронной почты не состоит из 44 символов (как в случае с шестнадцатеричной кодировкой), запрос не будет выполнен и появится сообщение об ошибке, например email must be encoded using TO_BASE64(SHA256(email)).
  • Проверьте коэффициент соответствия. Например, используйте запрос Рассчитать коэффициент соответствия. В противном случае вы получите меньше сопоставленных пользователей. Если совпадений меньше 1000, то выполнение завершается ошибкой Minimum match count check failed..
  • Используйте только одно подключение UPDM для каждого аккаунта. У подключений UPDM нет целевой таблицы. Каждое подключение UPDM в аккаунте и каждый запрос Private Cloud Match записывают данные в одну и ту же таблицу сопоставления, и каждый успешный запуск заменяет ее. Чтобы сопоставить данные из нескольких источников, сначала объедините их в одну таблицу или файл.
Собственные данные

Для каждого столбца выберите Тип (Тип данных на странице сведений о подключении). Связи преобразуют каждое исходное значение в этот тип, а целевой столбец получает тип BigQuery, указанный здесь:

Тип Целевой столбец Значения, которые он преобразует Значения, которые становятся NULL
STRING (по умолчанию) STRING Любое значение в виде текста. В BigQuery 123 преобразуется в "123", а TRUE – в "true". Из Cloud Storage текст извлекается без изменений. Значение атрибута BYTES, не являющееся текстом в кодировке UTF-8
HASH STRING То же, что и STRING. Сервис "Связи" не хеширует и не проверяет значение. То же, что и STRING.
INTEGER INT64 Целые числа и числа, записанные текстом, например "42". В BigQuery десятичные числа усекаются: 1.9 становится 1. Другие значения, например "abc", TRUE или дата. Из Cloud Storage – также десятичное число, например 1.9.
DOUBLE FLOAT64 Числа и их текстовые представления, например "1.5". Другие значения, например TRUE или дата.
DATE DATE Значения DATE и текст в формате "год-месяц-день", например 2026-01-15 или 2026-1-5. Другие значения, например 01/15/2026, 20260115, TIMESTAMP или DATETIME.
TIMESTAMP TIMESTAMP Значения TIMESTAMP, DATETIME и DATE, а также текст, например 2026-01-15 10:00:00 или 2026-01-15T10:00:00-08:00. Значение без часового пояса считывается как UTC, а дата становится полуночью по UTC. Другие значения, например время эпохи Unix (1768471200).
  • Если значение не удается преобразовать, выполнение не прерывается. Оно импортируется как NULL, и Connections не сообщает об этом, поэтому проверьте целевую таблицу после первого запуска.
  • Выберите тип, который подходит для ваших данных. Для источника BigQuery выберите тип, соответствующий исходному столбцу: STRING для STRING, INTEGER для INT64, DOUBLE для FLOAT64, DATE для DATE и TIMESTAMP для TIMESTAMP. Эти значения импортируются без изменений. Для источника Cloud Storage каждое значение CSV является текстом: выберите тип значений в столбце, например INTEGER для 42 или DATE для 2026-01-15. Если в каждой строке столбца указано значение NULL, выберите STRING или сначала преобразуйте значения в исходных данных.
  • Некоторые типы BigQuery не сопоставляются. Если вы сопоставите столбец ARRAY, STRUCT, JSON или GEOGRAPHY, то не сможете сохранить подключение.
  • При каждом запуске целевая таблица полностью заменяется. Они не добавляются. Если в источнике нет строк, целевой диапазон будет пустым. Не используйте в качестве целевой исходную таблицу или таблицу, данные которой вам нужно сохранить.
Перемещенные подключения

Преобразования пока недоступны в обновленном интерфейсе подключений: вы не можете добавить преобразование в поле, и оно не показывается в сопоставлениях полей. Подключение, перенесенное в обновленный интерфейс, сохраняет преобразования своих полей, например вычисление хеша (хеширование SHA-256).

  • В подключении собственных данных поле с преобразованием получает значение, которое создает преобразование, а не преобразование Тип, и вы не можете изменить его Тип. В подключении UPDM к этому значению по-прежнему применяются правила UPDM.
  • Поле UPDM, в котором использовался вычисляемый хеш, по-прежнему хешируется в Connections. Исходные значения не должны быть хешированы, но должны быть отформатированы, как описано в разделе Форматирование данных для ввода. Если значение уже хешировано, оно будет хешировано повторно и не совпадет. Чтобы хешировать значения самостоятельно, удалите сопоставление полей и добавьте его снова.
  • Переносятся только следующие преобразования:

    • Вычислите хеш с помощью SHA-256 (Base64 или шестнадцатеричный формат), за исключением UPDM user_id, country или zip_code, которые должны оставаться в виде обычного текста.
    • Форматирование в нижнем или верхнем регистре.
    • Преобразование в строку.
    • Синтаксический анализ временных меток без часового пояса по умолчанию (до 10 полей подключения).
    • Два из первых трех подряд, например преобразование в нижний регистр, а затем вычисление хеша.

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

    • В подключении UPDM расчет хеша подходит для email, phone, first_name и last_name. Форматирование в нижнем или верхнем регистре и преобразование в строку подходят для user_id, country и zip_code. Синтаксический анализ временной метки не соответствует ни одному полю.
    • При подключении собственных данных хеш вычислений соответствует столбцу STRING или HASH. Форматирование в нижнем или верхнем регистре и преобразование в строку подходят для столбца STRING. Синтаксический анализ временных меток подходит для столбца TIMESTAMP.

    Связь с любым другим преобразованием, например объединением или разделением полей, или с преобразованием, которое не подходит для его поля, не перемещается.

Требования к столбцам CSV-файла в Cloud Storage

  • Добавьте строку заголовка. Первая строка пропускается, названия столбцов не используются.
  • В файле должны быть только сопоставленные исходные столбцы. Если в файле есть лишние столбцы, запустить его не удастся.
  • Собственные данные. Столбцы должны быть расположены в том же порядке, что и сопоставления полей.
  • Сопоставление данных, предоставленных пользователями. Столбцы должны быть расположены в следующем порядке (оставьте только те поля, которые вы сопоставляете): user_id, email, phone, first_name, last_name, country, zip_code. Порядок строк сопоставления не имеет значения.
  • Если порядок столбцов будет другим, система не обнаружит этого, и значения будут загружены в неправильные поля (или снизится коэффициент соответствия) без сообщения об ошибке.

Поддерживаемые источники данных и ограничения на подключения

  • Источники данных. Поддерживаются только источники BigQuery и Cloud Storage.
  • Названия таблиц BigQuery. Для исходных и целевых таблиц BigQuery необходимо указывать полное название project.dataset.table.
  • Пути к файлам Cloud Storage. Укажите URI одного файла, например gs://bucket/path/file.csv. Пути с подстановочными знаками * или ? не поддерживаются.
  • Названия подключений. Каждое подключение в аккаунте должно иметь уникальное название.

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

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

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

Идентификатор пользователя

  • Тип данных: BYTES
  • Хеширование: нет

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

  • Удалите начальные и конечные пробелы.
  • Не используйте заглавные буквы.
  • Адреса электронной почты должны включать доменное имя (например, gmail.com или mail.ru).
  • Удалите надстрочные знаки, например замените è, é, ê или ë на e.
  • удалить все точки (.), предшествующие доменному имени, в адресах электронной почты, оканчивающихся на gmail.com и googlemail.com.
  • Хеширование: SHA256 с кодировкой Base64

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

Недопустимый вариант: TO_BASE64(SHA256("JéffersonLôvesHiking@gmail.com"))

Телефон

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

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

Недопустимый вариант: TO_BASE64(SHA256("(800) 555-0101"))

Имя

  • Удалить пробелы
  • Не используйте заглавные буквы.
  • Удалите все префиксы, например "г-жа", Mr., Ms., CANNOT TRANSLATE
  • Не удаляйте надстрочные знаки, например è, é, ê или ë.
  • Хеширование: SHA256 с кодировкой Base64

Действителен до: TO_BASE64(SHA256("daní"))

Недопустимый вариант: TO_BASE64(SHA256("Daní"))

Фамилия

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

Действителен до: TO_BASE64(SHA256("délacruz"))

Недопустимый вариант: TO_BASE64(SHA256("dé la Cruz, Jr."))

Страна

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

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

Недопустимые значения: United States of America или USA.

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

  • Не хешируйте почтовые индексы.
  • Можно указывать почтовые индексы США и других стран
  • Используйте только буквы A–Z, цифры, пробелы и дефисы (не более 20 символов).
  • Для США:
    • Допускаются пятизначные индексы, например 94043.
    • После пятизначного индекса можно указать четырехзначный добавочный код, например 94043-1351 или 940431351.
  • Для остальных стран:
    • Не нужно преобразовывать буквы в строчные или удалять пробелы и дефисы.
    • Добавочные почтовые индексы не допускаются.
  • Хеширование: нет

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

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

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

Проложить маршрут

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

Ключи для объединения

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

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

Как создать таблицу соответствий

  1. Нажмите add Создать > Запрос.
  2. Скопируйте шаблон запроса Создание таблицы соответствий в частном облаке и вставьте его в редактор запросов. Если ваши данные не хешированы, вы можете использовать шаблон Создание таблицы соответствий в частном облаке (с хешированием).

    /* 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. Замените названия параметров названиями столбцов, чтобы обеспечить правильное присвоение псевдонимов.

  4. Нажмите Сохранить.

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

Перенос существующих подключений

Существующие подключения на вкладке Подключения переносятся в обновленный раздел "Подключения", встроенный непосредственно в Ads Data Hub. Обновленные подключения считывают источники и записывают целевые сервисы, используя сервисный аккаунт, указанный в разделе Настройки > Подробности > Сервисный аккаунт (обычно это service-<number>@gcp-sa-adsdatahub.iam.gserviceaccount.com), а не устаревшие сервисные аккаунты Data Fusion, Dataproc и UPDM.

До переноса подключений выполните следующие задачи:

  1. Предоставьте разрешения сервисному аккаунту. Предоставьте сервисному аккаунту, указанному в разделе Settings (Настройки) > Details (Сведения) > Service account (Сервисный аккаунт) (обычно service-<number>@gcp-sa-adsdatahub.iam.gserviceaccount.com), необходимые роли источника и назначения (roles/bigquery.dataViewer, roles/storage.objectViewer и roles/bigquery.dataEditor в наборах данных назначения, не используемых по умолчанию). Подключения с нечитаемыми, удаленными или измененными источниками могут быть перенесены (особенно источники Cloud Storage, которые не проверяются во время переноса), но запуски будут завершаться ошибкой, пока вы не предоставите доступ или не исправите источник.
  2. Преобразуйте неподдерживаемые подключения. Подключения со следующими конфигурациями не будут перенесены. Преобразуйте их в поддерживаемые подключения BigQuery или Cloud Storage:

    • Другие источники данных (Amazon S3, Snowflake, MySQL, PostgreSQL, Amazon Redshift, sFTP или Salesforce). Сначала разместите данные в BigQuery или Cloud Storage, а затем создайте подключение к BigQuery или Cloud Storage.
    • Неподдерживаемые сопоставления полей или типы данных. Обновите или заново создайте подключение, чтобы оно соответствовало требованиям к полям и типам данных.
    • Неподдерживаемые преобразования. Переносятся только преобразования, перечисленные в разделе Перенесенные подключения. Удалите все остальные преобразования, например объединение или разделение полей, и выполните эти действия в исходных данных.
    • Пути с подстановочными знаками в Cloud Storage (* или ?). Замените URI с подстановочным знаком на URI одного файла или сначала загрузите файлы в BigQuery.
    • Названия, которые уже используются в Ads Data Hub. Переименуйте подключение, если в вашем аккаунте уже есть запрос или подключение, созданное в обновленном интерфейсе, с таким же названием.

    Существующие подключения с одинаковыми названиями будут перенесены. Самое старое сохранит название, а остальные получат суффикс, например (2) или (3).

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

Данные, соответствующие запросу

Как отправлять запросы к таблицам соответствий

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

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

В схеме 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. Например, если в исходной таблице содержатся данные о пользователе А и пользователе Б, но был сопоставлен только пользователь А, то пользователям Б не будет в таблице соответствий.

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

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

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

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

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

Подсчет количества подходящих пользователей

Этот запрос позволяет подсчитать количество сопоставленных пользователей в таблице показов Google Рекламы.

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

SELECT COUNT(DISTINCT user_id)
FROM adh.google_ads_impressions_updm

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

Не все пользователи подходят для сопоставления. Например, пользователи, не вошедшие в аккаунт, дети и пользователи, не давшие согласие, не сопоставляются с помощью UPDM. Поле is_updm_eligible позволяет точнее рассчитывать коэффициент соответствия данных, предоставленных пользователями. Обратите внимание, что поле 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 Рекламы

В этом запросе показано, как объединить собственные данные с данными 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

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

Ответы на часто задаваемые вопросы о сопоставлении данных, предоставленных пользователями, можно найти в Справочном центре.