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

Data Manager API hỗ trợ 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 quan.

• 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 giúp nhận dạng 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, đừng xoá dấu chấm hoặc dấu cộng. Ví dụ: [e-mail] → [e-mail] Khoảng trắng Cắt bỏ khoảng trắng ở đầu, cuối và giữa. Băm Băm bằng thuật toán SHA-256 và mã hoá các byte băm.
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 và mã hoá các byte băm.
address	AddressInfo đối tượng Tham khảo thông số kỹ thuật về định dạng AddressInfo.

Định dạng: AddressInfo

Hãy sử dụng các nguyên tắc định dạng sau đây để 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 và mã hoá các byte băm.
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 và mã hoá các byte băm.
region_code	Định dạng string Mã ISO-3166-1 alpha-2 gồm hai 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à phần mở rộng gồm 4 chữ số. Việc sử dụng phần mở rộng gồm 4 chữ số có thể cải thiện 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 và mã hoá các byte băm.
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 tên viết tắt gồm hai 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, chữ hoa hay chữ thường đều được (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 danh sách mã nhận dạng vào trường pair_ids của đối tượng PairData. Đị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 phòng dữ liệu sạch cung cấp bằng thuật toán SHA-256.

2. Mã hoá các byte băm bằng 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 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 Mobile ID. Không băm mã nhận dạng cho thiết bị di động.

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

Nếu bạn 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ề giờ UTC của 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à trước giờ UTC 4 tiếng tại thời điểm đó: 2025-08-08T13:18:44.291-04:00

• Múi giờ PDT, chậm hơn 7 giờ so với 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 giờ UTC và không áp dụng giờ mùa hè: 2025-08-08T22:18:44.291+09:00

Nếu bạn 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. Dưới đây là các giá trị seconds và nanos cho giờ UTC ngày 8 tháng 8 năm 2025 lúc 17:18:44.291:

• seconds: 1754683124

• nanos: 291000000

Mã hóa

Yêu cầu về việc mã hoá sẽ khác nhau tuỳ thuộc vào việc bạn có mã hoá dữ liệu người dùng hay không:

• Dữ liệu người dùng chưa mã hoá: Mã hoá các byte băm SHA-256 bằng mã hoá thập lục phân (hex) hoặc mã hoá Base64.

• Dữ liệu người dùng đã mã hoá: Nếu mã hoá dữ liệu người dùng, bạn phải mã hoá Base64 các byte băm thô trước khi mã hoá. Hệ thập lục phân không được hỗ trợ cho hàm băm trước khi mã hoá. Sau đó, bạn có thể mã hoá văn bản mật mã thu được bằng cách sử dụng phương thức mã hoá thập lục phân hoặc Base64.

Lưu ý: 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.