設定使用者資料格式

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

• UserData：使用者提供的資料，例如電子郵件地址或電話號碼。
• IpData：IP 資料，例如 IP 位址和相關時間戳記。
• PairData：發布商及廣告主使用者身分資料比對 (PAIR) ID。
• MobileData：可識別行動裝置的資料。

UserData 需求條件

UserData 物件是 UserIdentifier 物件的集合。每個 UserIdentifier 都必須具備下表中的其中一個屬性。

UserIdentifier
email_address	格式 string 轉換為小寫。 如果電子郵件地址的網域為 gmail.com 或 googlemail.com： 移除 @ 符號前的所有點號 (.)。 從本機部分移除加號 (+)，並移除後方所有字元。 示例： cloudy.sanfrancisco+shopping@gmail.com → cloudysanfrancisco@gmail.com 如果電子郵件地址的網域不是 gmail.com 或 googlemail.com，請勿移除點號或加號。 範例：user.name+NYC@Example.com → user.name+nyc@example.com 空白字元 移除開頭、結尾和中間的空白字元。 雜湊 使用 SHA-256 演算法進行雜湊處理。 使用十六進位或 Base64 編碼方式，為雜湊位元組編碼。
phone_number	格式 string 請使用 E.164 格式。 包含加號 (+) 和國家/地區代碼。加號後的所有字元都必須是數字。 舉例來說，美國電話號碼 (800)555-0100 應格式化並正規化為 +18005550100。 空白字元 移除開頭和結尾的空白字元。 雜湊 使用 SHA-256 演算法進行雜湊處理。 使用十六進位或 Base64 編碼方式，為雜湊位元組編碼。
address	AddressInfo 物件 請參閱AddressInfo格式規格。

AddressInfo格式

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

AddressInfo
given_name	格式 string 轉換為小寫。 請勿加入 Mrs. 等前置字元 空白字元 移除開頭和結尾的空白字元。 雜湊 使用 SHA-256 演算法進行雜湊處理。 使用十六進位或 Base64 編碼方式，為雜湊位元組編碼。
family_name	格式 string 轉換為小寫。 請勿加入姓名後綴，例如 Jr. 空白字元 移除開頭和結尾的空白字元。 雜湊 使用 SHA-256 演算法進行雜湊處理。 使用十六進位或 Base64 編碼方式，為雜湊位元組編碼。
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 演算法進行雜湊處理。 使用十六進位或 Base64 編碼方式，為雜湊位元組編碼。
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. 使用發布商金鑰，透過 EC 可交換密碼，加密 PAIR 使用者清單的雜湊位元組。
3. 使用十六進位或 Base64 編碼加密資料。

MobileData 需求條件

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

時間戳記格式

如果 Timestamp 欄位使用 JSON 格式，例如 Event 的 timestamp 和 last_updated_timestamp，請使用 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
• 太平洋夏令時間時區，當時比世界標準時間早 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 編碼時，編碼輸出內容的字母大小寫很重要。