עיצוב של נתוני משתמשים

ה-API של המרכז לניהול נתונים תומך בהעלאה של כמה סוגים של נתוני משתמשים. כדי שהנתונים יתקבלו ויעובדו בהצלחה, צריך לפעול לפי דרישות הפורמט, הגיבוב והקידוד של כל רכיב נתונים.

• ‫UserData: פרטים שהמשתמשים סיפקו, כמו כתובת אימייל או מספר טלפון.
• ‫PairData: מזהים של Publisher Advertiser Identity Reconciliation (התאמה בין נתוני המשתמשים של בעלי תוכן דיגיטלי לנתוני לקוחות של מפרסמים,‏ PAIR).
• ‫MobileData: נתונים שמזהים מכשיר נייד.

UserData דרישות

אובייקט UserData הוא אוסף של אובייקטים מסוג UserIdentifier. לכל UserIdentifier יש בדיוק אחד מהמאפיינים שבטבלה הבאה.

UserIdentifier
email_address	פורמט string המרת האותיות לאותיות קטנות. אם כתובת האימייל כוללת את הדומיין gmail.com או googlemail.com, צריך להסיר את כל הנקודות (.) לפני הסמל @. רווח לבן חיתוך רווחים לבנים בתחילת הטקסט, בסופו ובאמצעו. גיבוב (hashing) מבצעים גיבוב באמצעות אלגוריתם SHA-256. מקודדים את בייטי הגיבוב באמצעות קידוד הקסדצימלי או קידוד Base64.
phone_number	פורמט string צריך להשתמש בפורמט E.164. צריך לכלול את סימן הפלוס (+) ואת קוד המדינה. כל התווים אחרי סימן הפלוס חייבים להיות ספרות. לדוגמה, מספר הטלפון בארה"ב [phone] צריך להיות בפורמט מנורמל של [phone]. רווח לבן חיתוך רווחים לבנים בתחילת הטקסט או בסופו. גיבוב (hashing) מבצעים גיבוב באמצעות אלגוריתם SHA-256. מקודדים את בייטי הגיבוב באמצעות קידוד הקסדצימלי או קידוד Base64.
address	AddressInfo אובייקט מידע נוסף מפורט בAddressInfo מפרט הפורמט.

פורמט של AddressInfo

כדי ליצור את מאפיין address של UserIdentifier, צריך לפעול לפי הנחיות הפורמט הבאות.

AddressInfo
given_name	פורמט string המרת האותיות לאותיות קטנות. אל תוסיפו תחיליות כמו Mrs. רווח לבן חיתוך רווחים לבנים בתחילת הטקסט או בסופו. גיבוב (hashing) מבצעים גיבוב באמצעות אלגוריתם SHA-256. מקודדים את בייטי הגיבוב באמצעות קידוד הקסדצימלי או קידוד Base64.
family_name	פורמט string המרת האותיות לאותיות קטנות. אל תוסיפו סיומות כמו Jr. רווח לבן חיתוך רווחים לבנים בתחילת הטקסט או בסופו. גיבוב (hashing) מבצעים גיבוב באמצעות אלגוריתם SHA-256. מקודדים את בייטי הגיבוב באמצעות קידוד הקסדצימלי או קידוד Base64.
region_code	פורמט string קוד בן שני תווים בפורמט ISO-3166-1 alpha-2. רווח לבן חיתוך רווחים לבנים בתחילת הטקסט או בסופו. גיבוב (hashing) אין לבצע גיבוב של region_code.
postal_code	פורמט string אפשר להשתמש במיקוד של ארה"ב וגם של מדינות אחרות. לכתובות בארה"ב, אפשר להשתמש במיקוד בן 5 ספרות או במיקוד בן 5 ספרות ואחריו תוסף בן 4 ספרות. שימוש בתוספת של 4 ספרות עשוי לשפר את אחוז הלקוחות לטירגוט. בכל שאר המדינות, אין להשתמש בתוספות למיקוד. רווח לבן חיתוך רווחים לבנים בתחילת הטקסט או בסופו. גיבוב (hashing) אין לבצע גיבוב של postal_code.

PairData דרישות

מאכלסים את השדה pair_ids של אובייקט PairData ברשימה של מזהים. כדי לעצב כל רכיב ברשימה, מבצעים את הפעולות הבאות:

1. מגבבים את נתוני ה-PII שסופקו בחדר הנקי באמצעות אלגוריתם SHA-256.
2. מצפינים את בייטי הגיבוב באמצעות צופן EC קומוטטיבי, תוך שימוש במפתח של בעל התוכן הדיגיטלי עבור רשימת המשתמשים ב-PAIR.
3. מקודדים את הנתונים המוצפנים באמצעות קידוד הקסדצימלי או קידוד Base64.

MobileData דרישות

מאכלסים את השדה mobile_ids של אובייקט MobileData ברשימה של מזהים לנייד. אל תבצעו גיבוב (hash) של מזהי מכשירים ניידים.

הפורמט של חותמת הזמן

אם משתמשים בפורמט JSON בשדות של Timestamp, כמו timestamp ו-last_updated_timestamp של Event, צריך להשתמש בפורמט RFC 3339. דוגמאות לזמן UTC ב-8 באוגוסט 2025 בשעה 17:18:44.291 בפורמט RFC 3339 ובאזורי זמן שונים:

• אזור זמן UTC: ‏2025-08-08T17:18:44.291Z
• אזור זמן EDT, שהיה 4 שעות לפני UTC באותו זמן: 2025-08-08T13:18:44.291-04:00
• אזור זמן PDT, שהיה 7 שעות לפני UTC באותו זמן: 2025-08-08T10:18:44.291-07:00
• אזור הזמן של טוקיו, יפן, שמקדים את UTC ב-9 שעות ולא חל בו שעון קיץ: 2025-08-08T22:18:44.291+09:00

אם משתמשים בפורמט של מאגר פרוטוקולים, צריך להגדיר את seconds ואפשר גם את nanos כשיוצרים את Timestamp. אלה הערכים של seconds ו-nanos לשעה 17:18:44.291 ב-8 באוגוסט 2025 לפי שעון UTC:

• seconds: 1754683124
• nanos: 291000000

קידוד

כשמקודדים נתונים, חשוב לזכור את הנקודות הבאות:

• כשמשתמשים בקידוד הקסדצימלי (hex), האותיות בקידוד הפלט לא משנות.
• כשמשתמשים בקידוד Base64, יש חשיבות לאותיות הרישיות והקטנות בפלט הקידוד.