設定使用者資料格式

Data Manager API 支援上傳多種類型的使用者資料。請遵循各資料元素的格式、雜湊和編碼規定，確保資料能順利接收及處理。

• UserData：使用者提供的資料，例如電子郵件地址或電話號碼。

• IpData：IP 資料，例如 IP 位址和相關聯的時間戳記。

• PairData：發布商及廣告主使用者身分資料比對 (PAIR) ID。

• MobileData：識別行動裝置的資料。

UserData 需求條件

UserData 物件是 UserIdentifier 物件的集合。每個 UserIdentifier 都只有下表中的其中一個屬性。

UserIdentifier
email_address	格式 string 轉換為小寫。 如果電子郵件地址含有 gmail.com 或 googlemail.com 網域： 移除 @ 符號前面的所有點號 (.)。 移除本機部分的加號 (+) 和其後的所有字元。 範例：[e-mail] → [e-mail] 如果電子郵件地址的網域不是 gmail.com 或 googlemail.com，請勿移除點號或加號。 範例：[e-mail] → [e-mail] 空白字元 移除開頭、結尾和中間的空白字元。 雜湊 使用 SHA-256 演算法進行雜湊，並編碼雜湊位元組。
phone_number	格式 string 請使用 E.164 格式。 請加上加號 (+) 和國家/地區代碼。加號後方的所有字元都必須是數字。 舉例來說，美國電話號碼 [phone] 應格式化並正規化為 [phone]。 空白字元 移除開頭和結尾的空白字元。 雜湊 使用 SHA-256 演算法進行雜湊，並編碼雜湊位元組。
address	AddressInfo 物件 請參閱 AddressInfo 格式規格。

AddressInfo格式

請按照下列格式規範，建構 UserIdentifier 的 address 屬性。

AddressInfo
given_name	格式 string 轉換為小寫。 請勿加入 Mrs. 等前置字元 空白字元 移除開頭和結尾的空白字元。 雜湊 使用 SHA-256 演算法進行雜湊，並編碼雜湊位元組。
family_name	格式 string 轉換為小寫。 請勿加入 Jr. 等後置字詞 空白字元 移除開頭和結尾的空白字元。 雜湊 使用 SHA-256 演算法進行雜湊，並編碼雜湊位元組。
region_code	格式 string 雙字元 ISO-3166-1 alpha-2 代碼。 空白字元 移除開頭和結尾的空白字元。 雜湊 請勿對 region_code 進行雜湊處理。
postal_code	格式 string 美國與國際郵遞區號皆可使用。 如果是美國地址，請使用 5 位數或 5 位數加上 4 位數分機號碼。使用 4 碼額外編碼可能有助於提升媒合率。 如為所有其他國家/地區，請勿使用郵遞區號的額外編碼。 空白字元 移除開頭和結尾的空白字元。 雜湊 請勿對 postal_code 進行雜湊處理。
address_line	格式 string 僅用於 Google Analytics。 使用者地址的街道和門牌號碼。 轉換為小寫。 移除符號字元。 空白字元 移除開頭和結尾的空白字元。 雜湊 使用 SHA-256 演算法進行雜湊，並編碼雜湊位元組。
city	格式 string 僅用於 Google Analytics。 使用者地址的城市。 轉換為小寫。 移除符號字元。 空白字元 移除開頭和結尾的空白字元。 雜湊 請勿對 city 進行雜湊處理。
administrative_area	格式 string 僅用於 Google Analytics。 使用者地址的行政區 (州或省)。 請使用兩個字母的縮寫 (例如 ca) 或全名 (例如 california)。 轉換為小寫。 移除符號字元。 空白字元 移除開頭和結尾的空白字元。 雜湊 請勿對 administrative_area 進行雜湊處理。

IpData 需求條件

IpData 物件具有下列屬性。

IpData
ip_address	格式 string IPv4 或 IPv6 位址。 IPv6 位址不區分大小寫 (大寫或小寫皆可)。 空白字元 移除開頭和結尾的空白字元。 雜湊 請勿對 ip_address 進行雜湊處理。

PairData 需求條件

在 PairData 物件的 pair_ids 欄位中填入 ID 清單。請按照下列步驟設定清單中每個元素的格式：

1. 使用 SHA-256 演算法，對資料無塵室提供的 PII 資料進行雜湊處理。

2. 使用 PAIR 使用者名單的發布商金鑰，以 EC 交換密碼加密雜湊位元組。

3. 使用十六進位或 Base64 編碼，為加密資料編碼。

MobileData 需求條件

在 MobileData 物件的 mobile_ids 欄位中填入數位身分證件 清單。請勿將行動 ID 雜湊處理。

時間戳記格式

如果 Timestamp 欄位 (例如 Event 的 timestamp 和 last_updated_timestamp) 使用 JSON 格式，請採用 RFC 3339 格式。以下列舉幾個範例，說明 2025 年 8 月 8 日下午 5:18:44.291 的世界標準時間，在 RFC 3339 格式和不同時區中的表示方式：

• 世界標準時間時區：2025-08-08T17:18:44.291Z

• 北美東部夏令時間時區，當時比世界標準時間早 4 小時： 2025-08-08T13:18:44.291-04:00

• 太平洋夏令時間 (PDT) 時區，當時比世界標準時間 (UTC) 慢 7 小時： 2025-08-08T10:18:44.291-07:00

• 日本東京的時區比世界標準時間早 9 小時，且不採用日光節約時間： 2025-08-08T22:18:44.291+09:00

如果使用通訊協定緩衝區格式，請在建構 Timestamp 時設定 seconds，並視需要設定 nanos。以下是 2025 年 8 月 8 日下午 5:18:44.291 (世界標準時間) 的 seconds 和 nanos 值：

• seconds：1754683124

• nanos：291000000

編碼

編碼規定會因是否加密使用者資料而異：

• 未加密的使用者資料：使用十六進位編碼 (hex) 或 Base64 編碼，對 SHA-256 雜湊位元組進行編碼。

• 加密的使用者資料：如果您加密使用者資料，則必須先對原始雜湊位元組進行 Base64 編碼，再進行加密。預先加密雜湊不支援十六進位編碼。接著，您可以使用十六進位或 Base64 編碼，對產生的密文進行編碼。

注意： 使用十六進位編碼時，編碼輸出的大小寫並不重要。