比對使用者提供的資料

「比對使用者提供的資料」功能會彙整您收集的使用者第一方資料 (例如來自網站、應用程式或實體商店的資訊),以及該使用者在所有 Google 廣告資料 (包括 Google 自營媒體資料) 中的登入活動記錄。這包括透過 Google Marketing Platform (GMP) 產品購買的資料,例如使用 Display & Video 360 購買的 YouTube 廣告空間。不支援其他非 Google 擁有和營運的 GMP 產品。

廣告事件必須連結到 Google 廣告資料中的登入使用者,才能比對使用者提供的資料。

本文將說明「比對使用者提供的資料」功能,並提供設定和使用指南。

私有雲比對總覽

如要取得有價值的廣告洞察資料,通常需要整合多個來源的資料。如要自行建構解決方案來處理這項資料管道問題,需要投入大量時間和工程資源。廣告資料中心私有雲比對功能提供廣告資料中心查詢範本,可在 BigQuery 建立比對資料表,並用於廣告資料中心查詢,比對廣告資料和第一方資料,簡化上述程序。使用第一方資料讓查詢內容更豐富,不僅可帶來更豐富的客戶體驗,也更能因應整個產業的廣告追蹤變化。

「比對使用者提供的資料」功能只會比對 Google 自有自營廣告空間的登入使用者,因此不會受到第三方 Cookie 淘汰的影響。比第三方資料更能適應業界變遷,因此能提供更豐富的洞察資料,進而提高顧客參與度。

程序摘要

  1. 設定資料擷取和比對
    • 您:確認第一方資料位於 BigQuery,且服務帳戶具備讀取權限。請參閱「設定資料擷取」。
  2. 第一方資料擷取和比對
    • 您設定第一方資料格式,並上傳至 BigQuery 資料集。
    • 您可以建立私有雲比對分析查詢 並設定時間表,啟動資料比對要求。
    • Google 會彙整專案資料和 Google 自有資料 (包含 Google 的使用者 ID 和經雜湊處理的使用者提供資料),建立及更新比對表。
    • 請參閱「擷取第一方資料」
  3. 在廣告資料中心根據比對資料持續查詢
    • 您可以對對照表執行查詢,方法與在廣告資料中心執行一般查詢相同。請參閱「查詢比對資料」。

瞭解隱私權規定

收集顧客數位資料

使用「比對使用者提供的資料」功能時,您必須上傳第一方資料。這類資訊可能來自您的網站、應用程式、實體商店,或顧客直接提供給您的任何資訊。

須遵循的規定如下:

  • 確實在隱私權政策中聲明您會與第三方共用客戶資料,以便第三方代為提供服務,且您按照法律要求向使用者徵求共用資訊的同意聲明。
  • 僅使用 Google 核准的 API 或介面上傳顧客數位資料
  • 遵守所有適用法律和法規,包括任何適用的自我規範或業界準則

確認已取得第一方同意聲明

為確保能在廣告資料中心使用第一方資料,請務必確認您已根據歐盟地區使用者同意授權政策和廣告資料中心政策,取得適當的同意聲明,能與 Google 分享歐洲經濟區使用者的資料。這項規定適用於每個廣告資料中心帳戶,且您每次上傳新的第一方資料時,都必須更新同意聲明。任一使用者都可代表整個帳戶確認已取得同意聲明。

請注意,適用於分析查詢的 Google 服務查詢規則,同樣也適用於 UPDM 查詢。例如,建立對照表時,您無法對歐洲經濟區使用者執行跨服務查詢。

請參閱歐洲經濟區同意聲明規定,瞭解如何在廣告資料中心確認已取得同意聲明。

資料大小

為保護使用者隱私,比對使用者提供的資料功能會強制執行下列資料大小規定:

  • 使用者名單中至少須上傳 1,000 筆記錄。

設定資料擷取

開始前,請確認下列事項:

  • 第一方資料必須位於 BigQuery。如果您有 VPC-SC perimeter,這項第一方資料必須位於 VPC-SC 內。
  • 廣告資料中心服務帳戶必須具備第一方資料的讀取權限。
  • 第一方資料必須正確設定格式並經過雜湊處理。詳情請參閱下一節。

除此之外,私有雲比對功能不需要額外的新手上路流程。只要能執行分析查詢,就能執行 Private Cloud Match 查詢。

擷取及比對第一方資料

來源權限和連線相關規定

廣告資料中心連結會使用「設定」>「詳細資料」>「服務帳戶」下方顯示的服務帳戶 (通常是 service-<number>@gcp-sa-adsdatahub.iam.gserviceaccount.com)。請授予下列角色:

  • BigQuery 來源:來源資料集或資料表的 roles/bigquery.dataViewer (BigQuery 資料檢視者)。
  • Cloud Storage 來源:來源 bucket 或物件的 roles/storage.objectViewer (Storage 物件檢視者)。
  • 第一方資料匯入目的地:如果資料表不在預設資料集中,則為目的地資料集的 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 使用者的 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
  • 雜湊來源中的值。即使類型為 HASH,Connections 也不會對 email、phone、first_name 或 last_name 進行雜湊處理。例外狀況:如果連結已移至更新後的「連結」體驗,且在移動前,某個欄位使用了計算雜湊 (計算雜湊會為您雜湊處理資料欄),「連結」仍會雜湊處理該欄位。請勿雜湊該欄位的來源值,但要設定格式;請參閱「移動的連結」。
  • 在 BigQuery 來源資料表中,使用 STRING 欄。
    • email、phone、first_name 和 last_name 必須為 STRING。如果使用其他類型 (例如 INT64),則無法儲存連線。
    • user_id 也可以是 INT64 或 BYTES。非 UTF-8 文字的 BYTES 值會變成 NULL。
    • zip_code 也可以是 INT64,但 INT64 無法保留開頭的零 (02134 會儲存為 2134),因此這類郵遞區號無法比對。將郵遞區號儲存為 STRING。
  • 為每個資料列提供使用者 ID。所有包含 NULL 使用者 ID 的資料列都會計為一位使用者,因此最多只有一個資料列可以比對成功。使用者 ID 為空白的所有資料列也是如此。
  • 您的使用者 ID 會變成 BYTES。Connections 會將其轉換為 BYTES,也就是「設定輸入資料格式」列出的使用者 ID 類型,因此來源欄可以維持 STRING。舉例來說,INT64 值 42 會變成 b"42"。在 _updm 對照表中,這是 customer_data_user_id 欄。CAST(my_data.user_id AS BYTES) 無法用於 INT64 ID,因此如要加入,請先將其轉換為 STRING:customer_data_user_id = CAST(CAST(my_data.user_id AS STRING) AS BYTES)。
  • 如果電子郵件、電話或地址值空白或格式錯誤,系統就無法比對,但不會導致執行失敗。資料列仍可與其他值比對。舉例來說,純文字電子郵件、國家/地區 USA 或郵遞區號 94043.1351 無法比對。如要比對地址,資料列的四個地址欄都必須有有效值。
  • 在私有雲比對查詢中,如果值的格式不正確,整個查詢可能會失敗。如果您在廣告資料中心使用 CREATE OR REPLACE TABLE adh.updm_match_table 查詢建立對照表,而非使用連結,則適用此情況。舉例來說,如果電子郵件雜湊長度不是 44 個字元 (例如十六進位編碼),查詢就會失敗,並顯示 email must be encoded using TO_BASE64(SHA256(email)) 等錯誤。
  • 查看媒合率。例如,使用計算媒合率查詢。Connections 不會回報無法比對的值,因此比對成功的使用者人數會減少。如果符合條件的使用者不超過 1,000 人,執行作業會失敗,並顯示 Minimum match count check failed.
  • 每個帳戶只能使用一個 UPDM 連線。UPDM 連結沒有目的地資料表。帳戶中的每個 UPDM 連線和每個 Private Cloud Match 查詢都會寫入相同的比對表,且每次成功執行都會取代該表。如要比對多個來源的資料,請先將資料合併為一個表格或檔案。
第一方資料

為每個資料欄選擇「Type」(類型) (連線詳細資料頁面上的「Data Type」(資料類型))。Connections 會將每個來源值轉換為該類型,而目的地資料欄會取得此處列出的 BigQuery 類型:

類型 目的地資料欄 轉換的值 值變為 NULL
STRING (預設) STRING 任何值 (以文字形式表示)。在 BigQuery 中,123 會變成 "123",TRUE 則會變成 "true"。如果是 Cloud Storage,文字會保持原樣。 BYTES 值不是 UTF-8 文字
HASH STRING 與 STRING 相同。Connections 不會對值進行雜湊處理或檢查。 與 STRING 相同
INTEGER INT64 整數和數字文字,例如 "42"。在 BigQuery 中,小數會遭到截斷:1.9 變成 1。 其他值,例如 "abc"、TRUE 或日期。如果是 Cloud Storage,則同樣是小數,例如 1.9。
雙人房 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);日期會解讀為世界標準時間午夜。 其他值,例如 Unix 紀元時間 (1768471200)
  • 如果值無法轉換,執行作業不會失敗。系統會將其匯入為 NULL,且連結不會回報,因此請在首次執行後檢查目的地資料表。
  • 選擇適合資料的類型。如果是 BigQuery 來源,請選擇與來源資料欄相符的類型:STRING 選擇「STRING」、INT64 選擇「INTEGER」、FLOAT64 選擇「DOUBLE」、DATE 選擇「DATE」,以及 TIMESTAMP 選擇「TIMESTAMP」。這些值會直接匯入,不會變更。 如果是 Cloud Storage 來源,每個 CSV 值都是文字:請選擇資料欄中的值類型,例如 42 的 INTEGER 或 2026-01-15 的 DATE。如果資料欄在每一列中都顯示 NULL,請選擇「STRING」STRING,或先轉換來源資料中的值。
  • 部分 BigQuery 類型無法對應。如果對應 ARRAY、STRUCT、JSON 或 GEOGRAPHY 欄,就無法儲存連結。
  • 每次執行都會取代整個目的地資料表。不會附加。如果來源沒有資料列,目的地就會變成空白。請勿將來源資料表或需要保留資料的資料表設為目的地。
已移動的連線

更新後的「連結」服務尚不支援轉換功能,因此您無法在欄位中新增轉換,欄位對應也不會顯示轉換。移至更新版「連結」服務的連結,仍會保留欄位的轉換,例如計算雜湊 (SHA-256 雜湊)。

  • 在第一方資料連結中,含有轉換的欄位會取得轉換產生的值,而非「類型」轉換,且您無法變更其「類型」。在「比對使用者提供的資料」連結中,「比對使用者提供的資料」規則仍適用於該值。
  • 使用運算雜湊的 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 欄。

    如果連結含有其他轉換 (例如合併或分割欄位),或轉換與欄位不符,則不會移動。

Cloud Storage CSV 資料欄規定

  • 加入標頭列。系統會略過第一行,不使用其中的資料欄名稱。
  • 檔案必須包含對應的來源欄,不得多也不得少。多餘的資料欄會導致執行失敗。
  • 第一方資料:資料欄順序必須與欄位對應相同。
  • 比對使用者提供的資料:欄必須依此順序排列,且只保留您對應的欄位: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。
  • 輸入欄位必須採用字串格式。舉例來說,如果您使用 BigQuery SHA256 雜湊函式,請使用下列轉換:TO_BASE64(SHA256(user_data))。

使用者 ID

  • 資料類型:BYTES
  • 雜湊:無

電子郵件

  • 移除開頭和結尾的空白字元
  • 全部使用小寫字元
  • 為所有電子郵件地址加上網域名稱 (例如 gmail.com 或 hotmail.co.jp)
  • 移除重音符號,例如將 è、é、ê 或 ë 變更為 e
  • 移除 gmail.com 和 googlemail.com 電子郵件地址中,網域名稱前所有的半形句號 (.)
  • 雜湊:Base64 編碼 SHA256

有效期限:TO_BASE64(SHA256("jeffersonloveshiking@gmail.com"))

無效:TO_BASE64(SHA256("JéffersonLôvesHiking@gmail.com"))

電話

  • 移除空白字元
  • 請採用 E.164 格式,例如美國:+14155552671,英國:+442071838750
  • 移除所有特殊字元,但國家/地區代碼前的「+」除外
  • 雜湊:Base64 編碼 SHA256

有效期限:TO_BASE64(SHA256("+18005550101"))

無效:TO_BASE64(SHA256("(800) 555-0101"))

名字

  • 移除空白字元
  • 全部使用小寫字元
  • 移除所有前置字串,例如 Mrs.、先生、小姐、博士
  • 請勿移除重音符號,例如 è、é、ê 或 ë
  • 雜湊:Base64 編碼 SHA256

有效期限:TO_BASE64(SHA256("daní"))

無效:TO_BASE64(SHA256("Daní"))

姓氏

  • 移除空白字元
  • 全部使用小寫字元
  • 移除所有後置字串,例如 Jr.、Sr., 2nd、3rd、II、III、PHD、MD
  • 請勿移除重音符號,例如 è、é、ê 或 ë
  • 雜湊:Base64 編碼 SHA256

有效期限: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 個字元
  • 美國:
    • 可使用 5 碼郵遞區號,例如 94043
    • 也可使用 5 碼後加額外 4 碼的郵遞區號,例如 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()

Go

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

  Sample hashes:

    - Email 'test@gmail.com': h5JGBrQTGorO7q6IaFMfu5cSqqB6XTp1aybOD11spnQ=
    - Phone '+18005551212':   YdkRG+0+bZz8G8O1yzWkAmh8TxVGvuBhor1ET73WTEQ=
    - First name 'John':      ltljLzY1ZMwwMlIUCc8iqFLyAy7sCZ7VlnwNAAzsYHo=
    - Last name 'Doe':        eZ75KhGvkY4/t0HfQpNPO1aO0tk6wd908bjUGieTKm8=
  */
  package main

  import (
    "crypto/sha256"
    "encoding/base64"
    "fmt"
    "strings"
  )

  // Hash hashes an email, phone, first name, or last name into the correct format.
  func Hash(token string) string {
    formatted := strings.TrimSpace(strings.ToLower(token))
    hashed := sha256.Sum256([]byte(formatted))
    encoded := base64.StdEncoding.EncodeToString(hashed[:])
    return encoded
  }

  // PrintHash prints the hash for a token.
  func PrintHash(token string) {
    fmt.Printf("Hash: \"%s\"\t(Token: %s)\n", Hash(token), token)

  }

  func main() {
    PrintHash("test@gmail.com")
    PrintHash("+18005551212")
    PrintHash("John")
    PrintHash("Doe")
  }

Java

  package updm.hashing;

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

  import java.security.MessageDigest;
  import java.security.NoSuchAlgorithmException;
  import java.util.Base64;

  /**
  * Example of the hashing algorithm.
  *
  * <p>Sample hashes:
  *
  * <ul>
  *   <li>Email 'test@gmail.com': h5JGBrQTGorO7q6IaFMfu5cSqqB6XTp1aybOD11spnQ=
  *   <li>Phone '+18005551212': YdkRG+0+bZz8G8O1yzWkAmh8TxVGvuBhor1ET73WTEQ=
  *   <li>First name 'John': ltljLzY1ZMwwMlIUCc8iqFLyAy7sCZ7VlnwNAAzsYHo=
  *   <li>Last name 'Doe': eZ75KhGvkY4/t0HfQpNPO1aO0tk6wd908bjUGieTKm8=
  * </ul>
  */
  public final class HashExample {

  private HashExample() {}

  public static String hash(String token) {
    // Normalizes and hashes the input token using SHA-256 and Base64 encoding.
    String formattedToken = token.toLowerCase().strip();

    byte[] hash;
    try {
      hash = MessageDigest.getInstance("SHA-256").digest(formattedToken.getBytes(UTF_8));
    } catch (NoSuchAlgorithmException e) {
      throw new IllegalStateException("SHA-256 not supported", e);
    }

    return Base64.getEncoder().encodeToString(hash);
  }

  public static void printHash(String token) {
    // Calculates and prints the hash for the given token.
    System.out.printf("Hash: \"%s\"\t(Token: %s)\n", hash(token), token);
  }

  public static void main(String[] args) {
    // Executes hash calculations and prints results for sample tokens.
    printHash("test@gmail.com");
    printHash("+18005551212");
    printHash("John");
    printHash("Doe");
  }
  }

SQL

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

  The following code uses Google Standard SQL and can be run on BigQuery to generate match tables from unhashed data.

  Sample hashes:

    - Email 'test@gmail.com': h5JGBrQTGorO7q6IaFMfu5cSqqB6XTp1aybOD11spnQ=
    - Phone '+18005551212':   YdkRG+0+bZz8G8O1yzWkAmh8TxVGvuBhor1ET73WTEQ=
    - First name 'John':      ltljLzY1ZMwwMlIUCc8iqFLyAy7sCZ7VlnwNAAzsYHo=
    - Last name 'Doe':        eZ75KhGvkY4/t0HfQpNPO1aO0tk6wd908bjUGieTKm8=

  The unhashed input table schema is assumed to be:

  - Column name: UserID, Type: String
  - Column name: Email, Type: String
  - Column name: Phone, Type: String
  - Column name: FirstName, Type: String
  - Column name: LastName, Type: String
  - Column name: PostalCode, Type: String
  - Column name: CountryCode, Type: String
  */

  -- Creates a new table with Base64-encoded SHA-256 hashes of specified columns.
  CREATE TABLE `your_project_name.your_dataset_name.output_hashed_table_name`
  AS
  SELECT
    UserID,
    TO_BASE64(SHA256(LOWER(Email))) AS Email,
    TO_BASE64(SHA256(Phone)) AS Phone,
    TO_BASE64(SHA256(LOWER(FirstName))) AS FirstName,
    TO_BASE64(SHA256(LOWER(LastName))) AS LastName,
    PostalCode,
    CountryCode,
  FROM
    `your_project_name.your_dataset_name.input_unhashed_table_name`;

加入鍵值

某些使用者提供資料的組合比其他組合更有效。以下列出使用者提供的不同資料組合,並依相對強度排序。如果使用地址,則必須包含:名字、姓氏、國家/地區和郵遞區號。

  1. 電子郵件、電話、地址 (最強)
  2. 電話、地址
  3. 電子郵件、地址
  4. 電子郵件、電話
  5. 地址
  6. 電話
  7. 電子郵件 (最弱)

建立比對表格

  1. 依序點選「add 建立」>「 查詢」。
  2. 複製「Private cloud match table generation」(生成私有雲對照表) 查詢範本,並貼到查詢編輯器。選用:如果資料尚未經過雜湊處理,可以使用「Private cloud match table generation (with hashing)」(生成私有雲比對表 (進行雜湊處理)) 範本。

    /* 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. 按一下「執行」。您必須手動執行這項查詢,才能重新整理對照表。每次執行都會覆寫目前的比對表。

遷移現有連結

「連結」分頁中的現有連結,將移至直接內建於廣告資料中心的新版「連結」頁面。更新後的連結會使用「設定」>「詳細資料」>「服務帳戶」下方顯示的服務帳戶 (通常是 service-<number>@gcp-sa-adsdatahub.iam.gserviceaccount.com),讀取來源和寫入目的地,而非舊版 Data Fusion、Dataproc 和 UPDM 服務帳戶。

請在連結轉移之前完成下列待辦事項:

  1. 授予服務帳戶權限:依序前往「設定」>「詳細資料」>「服務帳戶」,將必要的來源和目的地角色 (roles/bigquery.dataViewer、roles/storage.objectViewer 和非預設目的地資料集的 roles/bigquery.dataEditor) 授予其中顯示的服務帳戶 (通常是 service-<number>@gcp-sa-adsdatahub.iam.gserviceaccount.com)。即使連線的來源無法讀取、已刪除或變更 (尤其是 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。
    • 廣告資料中心已有名稱:如果帳戶中已有相同名稱的查詢,或在更新後的「連結」頁面中建立的連結,請重新命名連結。

    如果現有連線的名稱相同,系統仍會遷移這些連線:最舊的連線會保留名稱,其他連線則會加上後置字串,例如 (2) 或 (3)。

  3. 刪除未使用的連線:刪除不再需要的過時連線。

查詢比對資料

查詢對照表

如果對照表包含足夠的資料,可以滿足隱私權檢查的條件,您就能針對資料表執行查詢。

第一方資料 (1PD) 的原始資料表以 my_data 表示。包括個人識別資訊 (PII) 和非 PII 資料。 與比對表相比,原始資料表代表範圍內的所有第一方資料,因此使用原始資料表可提供更多洞察資料,改善報表品質。

廣告資料中心結構定義中,每個包含 user_id 欄位的資料表,都會附帶一個對照表。以 adh.google_ads_impressions 資料表為例,廣告資料中心會產生名為 adh.google_ads_impressions_updm 的對照表,其中包含 User-ID。如果是政策排除聯播網資料表,系統會建立個別的對照表。以 adh.google_ads_impressions_policy_isolated_network 資料表為例,廣告資料中心會產生名為 adh.google_ads_impressions_policy_isolated_network_updm 的對照表,其中包含 User-ID。

這些資料表包含原始資料表的一部分使用者,user_id 會有相符項目。舉例來說,如果原始資料表包含使用者 A 和使用者 B 的資料,但只有使用者 A 成功比對,那麼使用者 B 就不會出現在對照表。

對照表包含另一個名為 customer_data_user_id 的資料欄,該欄會以位元組形式儲存使用者 ID。

編寫查詢時,請務必考慮欄位的類型。SQL 比較運算子會認為您要比較的常值類型相同。視第一方資料表儲存 user_id 的方式而定,您可能需要先為資料表中的值編碼,才能比對資料。您必須將彙整鍵轉換為位元組,才能成功比對:

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 欄位,更準確地計算「比對使用者提供的資料」媒合率。請注意,is_updm_eligible 欄位自 2024 年 10 月 1 日起提供。您無法使用這個欄位計算該日期之前的媒合率。

/* 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 常見問題」。