设置用户数据的格式

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 算法进行哈希处理。 使用十六进制或 Base64 编码对哈希字节进行编码。
phone_number	格式 string 请使用 E.164 格式。 应包含加号 (+) 和国家/地区代码。加号后面的所有字符都必须是数字。 例如，美国电话号码 [phone] 应格式化并归一化为 [phone]。 空格符 去除开头和结尾处的空格。 哈希技术 使用 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 的相关要求

使用 ID 列表填充 PairData 对象的 pair_ids 字段。使用以下步骤设置列表中每个元素的格式：

1. 使用 SHA-256 算法对数据分析平台提供的 PII 数据进行哈希处理。
2. 使用 PAIR 用户列表的发布商密钥通过 EC 可交换密码对哈希字节进行加密。
3. 使用十六进制或 Base64 编码对加密数据进行编码。

MobileData 的相关要求

使用移动 ID 列表填充 MobileData 对象的 mobile_ids 字段。请勿对移动 ID 进行哈希处理。

时间戳格式

如果使用 JSON 格式表示 Timestamp 字段（例如 Event 的 timestamp 和 last_updated_timestamp），请使用 RFC 3339 格式。以下是一些示例，展示了 2025 年 8 月 8 日下午 5:18:44.291 的世界协调时间 (UTC) 在 RFC 3339 格式和不同时区中的表示方式：

• UTC 时区：2025-08-08T17:18:44.291Z
• 美国东部夏令时 (EDT) 时区，当时比世界协调时间 (UTC) 早 4 小时：2025-08-08T13:18:44.291-04:00
• PDT 时区，当时比 UTC 早 7 小时：2025-08-08T10:18:44.291-07:00
• 日本东京的时区，比世界协调时间 (UTC) 早 9 小时，不实行夏令时： 2025-08-08T22:18:44.291+09:00

如果使用协议缓冲区格式，请在构建 Timestamp 时设置 seconds 和（可选）nanos。以下是 2025 年 8 月 8 日下午 5:18:44.291 的世界协调时间 (UTC) 的 seconds 和 nanos 值：

• seconds：1754683124
• nanos：291000000

编码

对数据进行编码时，请注意以下几点：

• 使用十六进制编码 (hex) 时，编码输出的大小写无关紧要。
• 使用 Base64 编码时，编码输出的大小写很重要。