Định dạng dữ liệu người dùng

Data Manager API hỗ trợ việc tải nhiều loại dữ liệu người dùng lên. Hãy tuân thủ các yêu cầu về định dạng, băm và mã hoá cho từng phần tử dữ liệu để dữ liệu của bạn được nhận và xử lý thành công.

• UserData: Dữ liệu do người dùng cung cấp, chẳng hạn như địa chỉ email hoặc số điện thoại.
• IpData: Dữ liệu IP, chẳng hạn như địa chỉ IP và dấu thời gian liên kết.
• PairData: Mã nhận dạng Điều chỉnh danh tính giữa nhà xuất bản và nhà quảng cáo (PAIR).
• MobileData: Dữ liệu xác định một thiết bị di động.

UserData yêu cầu

Đối tượng UserData là một tập hợp các đối tượng UserIdentifier. Mỗi UserIdentifier có đúng một trong các thuộc tính trong bảng sau.

UserIdentifier
email_address	Định dạng string Chuyển đổi thành chữ thường. Nếu địa chỉ email có miền gmail.com hoặc googlemail.com: Xoá tất cả dấu chấm (.) trước ký hiệu @. Xoá dấu cộng (+) khỏi phần cục bộ và xoá tất cả ký tự theo sau dấu cộng đó. Ví dụ: [e-mail] → [e-mail] Nếu địa chỉ email có miền khác với gmail.com hoặc googlemail.com, thì đừng xoá dấu chấm hoặc dấu cộng. Ví dụ: [e-mail] → [e-mail] Khoảng trắng Loại bỏ khoảng trắng ở đầu, cuối và giữa. Băm Băm bằng thuật toán SHA-256. Mã hoá các byte băm bằng phương thức mã hoá hex hoặc Base64.
phone_number	Định dạng string Sử dụng định dạng E.164. Nhập cả dấu cộng (+) và mã quốc gia. Tất cả các ký tự sau dấu cộng phải là chữ số. Ví dụ: số điện thoại ở Hoa Kỳ [phone] phải được định dạng và chuẩn hoá thành [phone]. Khoảng trắng Cắt bỏ khoảng trắng ở đầu và cuối. Băm Băm bằng thuật toán SHA-256. Mã hoá các byte băm bằng phương thức mã hoá hex hoặc Base64.
address	AddressInfo đối tượng Tham khảo quy cách định dạng AddressInfo.

Định dạng: AddressInfo

Hãy sử dụng các nguyên tắc định dạng sau để tạo thuộc tính address của UserIdentifier.

AddressInfo
given_name	Định dạng string Chuyển đổi thành chữ thường. Đừng thêm tiền tố như Mrs. Khoảng trắng Cắt bỏ khoảng trắng ở đầu và cuối. Băm Băm bằng thuật toán SHA-256. Mã hoá các byte băm bằng phương thức mã hoá hex hoặc Base64.
family_name	Định dạng string Chuyển đổi thành chữ thường. Đừng thêm hậu tố như Jr. Khoảng trắng Cắt bỏ khoảng trắng ở đầu và cuối. Băm Băm bằng thuật toán SHA-256. Mã hoá các byte băm bằng phương thức mã hoá hex hoặc Base64.
region_code	Định dạng string Mã ISO-3166-1 alpha-2 gồm 2 ký tự. Khoảng trắng Cắt bỏ khoảng trắng ở đầu và cuối. Băm Đừng băm region_code.
postal_code	Định dạng string Có thể sử dụng cả mã bưu chính của Hoa Kỳ và mã bưu chính quốc tế. Đối với địa chỉ ở Hoa Kỳ, hãy sử dụng 5 chữ số hoặc 5 chữ số theo sau là 4 chữ số bổ sung. Việc sử dụng phần mở rộng gồm 4 chữ số có thể giúp bạn tăng tỷ lệ khớp. Đối với tất cả các quốc gia khác, đừng sử dụng phần mở rộng của mã bưu chính. Khoảng trắng Cắt bỏ khoảng trắng ở đầu và cuối. Băm Đừng băm postal_code.
address_line	Định dạng string Chỉ dùng cho Google Analytics. Đường phố và số nhà trong địa chỉ của người dùng. Chuyển đổi thành chữ thường. Xoá các ký tự biểu tượng. Khoảng trắng Cắt bỏ khoảng trắng ở đầu và cuối. Băm Băm bằng thuật toán SHA-256. Mã hoá các byte băm bằng phương thức mã hoá hex hoặc Base64.
city	Định dạng string Chỉ dùng cho Google Analytics. Thành phố trong địa chỉ của người dùng. Chuyển đổi thành chữ thường. Xoá các ký tự biểu tượng. Khoảng trắng Cắt bỏ khoảng trắng ở đầu và cuối. Băm Đừng băm city.
administrative_area	Định dạng string Chỉ dùng cho Google Analytics. Khu vực hành chính (tiểu bang hoặc tỉnh) trong địa chỉ của người dùng. Sử dụng chữ viết tắt gồm 2 chữ cái (ví dụ: ca) hoặc tên đầy đủ (ví dụ: california). Chuyển đổi thành chữ thường. Xoá các ký tự biểu tượng. Khoảng trắng Cắt bỏ khoảng trắng ở đầu và cuối. Băm Đừng băm administrative_area.

IpData yêu cầu

Đối tượng IpData có các thuộc tính sau.

IpData
ip_address	Định dạng string Địa chỉ IPv4 hoặc IPv6. Đối với địa chỉ IPv6, trường hợp này không quan trọng (bạn có thể dùng chữ hoa hoặc chữ thường). Khoảng trắng Cắt bỏ khoảng trắng ở đầu và cuối. Băm Đừng băm ip_address.

PairData yêu cầu

Điền vào trường pair_ids của đối tượng PairData bằng danh sách mã nhận dạng. Định dạng từng phần tử trong danh sách theo các bước sau:

1. Băm dữ liệu PII do clean room cung cấp bằng thuật toán SHA-256.
2. Mã hoá các byte băm bằng một thuật toán mật mã giao hoán EC bằng khoá của nhà xuất bản cho danh sách người dùng PAIR.
3. Mã hoá dữ liệu đã mã hoá bằng cách sử dụng phương thức mã hoá hex hoặc Base64.

MobileData yêu cầu

Điền vào trường mobile_ids của đối tượng MobileData bằng danh sách mã nhận dạng thiết bị di động. Không băm mã nhận dạng thiết bị di động.

Định dạng dấu thời gian

Nếu sử dụng định dạng JSON cho các trường Timestamp, chẳng hạn như timestamp và last_updated_timestamp của Event, hãy sử dụng định dạng RFC 3339. Sau đây là một số ví dụ về thời gian UTC vào ngày 8 tháng 8 năm 2025 lúc 17:18:44.291 theo định dạng RFC 3339 và các múi giờ khác nhau:

• Múi giờ UTC: 2025-08-08T17:18:44.291Z
• Múi giờ EDT, tức là 4 giờ trước giờ UTC tại thời điểm đó: 2025-08-08T13:18:44.291-04:00
• Múi giờ PDT, tức là 7 giờ trước giờ UTC tại thời điểm đó: 2025-08-08T10:18:44.291-07:00
• Múi giờ của Tokyo, Nhật Bản, nhanh hơn 9 giờ so với UTC và không áp dụng giờ mùa hè: 2025-08-08T22:18:44.291+09:00

Nếu sử dụng định dạng vùng đệm giao thức, hãy đặt seconds và nanos (không bắt buộc) khi tạo Timestamp. Sau đây là các giá trị seconds và nanos cho thời gian UTC là 17:18:44.291 ngày 8 tháng 8 năm 2025:

• seconds: 1754683124
• nanos: 291000000

Mã hóa

Khi mã hoá dữ liệu, hãy lưu ý những điều sau:

• Trường hợp đầu ra mã hoá không quan trọng khi sử dụng mã hoá thập lục phân (hex).
• Trường hợp của đầu ra mã hoá rất quan trọng khi sử dụng phương thức mã hoá Base64.