כשכלי פרסום דיגיטלי מפעילים ממשקי API למדידה (Attribution Reporting API או Private Aggregation API), הדוחות המוצפנים נשלחים מדפדפן Chrome או מצד הלקוח לנקודת הקצה של הדיווח של כלי הפרסום הדיגיטלי, שהיא כתובת URL מסוג .well-known עם מקור הדיווח של כלי הפרסום הדיגיטלי. נקודת הקצה (endpoint) של הדיווח מתארחת על ידי טכנולוגיית הפרסום כדי לאסוף את הדוחות המוצפנים.
אלה נקודות הקצה לכל API:
Private Aggregation
- ניפוי באגים
[reporting-origin]/.well-known/private-aggregation/debug/report-shared-storage - בשידור חי בערוצים
[reporting-origin]/.well-known/private-aggregation/report-shared-storageאו/.well-known/private-aggregation/report-protected-audience
- ניפוי באגים
דוחות שיוך (Attribution)
- ניפוי באגים
[reporting-origin]/.well-known/attribution-reporting/debug/report-aggregate-attribution - בשידור חי
[reporting-origin]/.well-known/attribution-reporting/report-aggregate-attribution
- ניפוי באגים
ספקי טכנולוגיות פרסום יקבלו את הדוחות בפורמט JSON באמצעות קריאת POST. ספקי טכנולוגיית פרסום יאספו את הדוחות האלה בפורמט JSON וימירו אותם בהמשך לפורמט AVRO שמשמש את שירות הצבירה. אחרי ההמרה, דוחות AVRO נשמרים באחסון הענן של טכנולוגיית הפרסום, כדי שאפשר יהיה לאגד אותם בהמשך.
אחרי שספק טכנולוגיית הפרסום יהיה מוכן לאיחוד, הוא יפעיל בקשה לעבודת צבירה דרך שירות הצבירה, שבו הדוחות יאוחזרו מאחסון הענן של ספק טכנולוגיית הפרסום. שירות Aggregation מתארח באחסון הענן של טכנולוגיית הפרסום, וצריך לכלול תמונה ברשימת ההיתרים.
דוגמה לדוח שמתקבל:
Private Aggregation API
{
"aggregation_coordinator_origin": "https://publickeyservice.msmt.aws.privacysandboxservices.com",
"aggregation_service_payloads": [ {
"key_id": "1a2baa3f-5d48-46cf-91f0-772633c12640",
"payload": "8Cjr1s3FVkCYkjzBvyzJn14yardVjd5N4vLCA69LQAPbIkJ0B58hAqUGBCNXpvTjW9ZpIoZbCSiUOsUDuoA/S+tqVolLMkame6sWC07cfUmZcVsbU+La3pzTMtCgdtNc8MIWgD3C63CMw7rWroRlechewVUajvAYVK/0HJq0YyGrTiFZZm36zi0jjyHLAXKV8p1Lvy1d0o/wnBxC5oVo5BV6LPkxqQEcoYS2GyixUuht6wD0RzuH+BxxuH6vY/ynp2xDrnwftjvqwDUAxUWLFTunthM6BXZVxlrvOBim1h2dvPqWSyKZ5gafo+MgW9EM4SraavNM3XzZSCjdtAfSMJMrynSu2j0opyAq+9e1jq1xeYN00yZrJ0Y/GTI45IGjgCnVmvmuoI9ucW2SnXP31CQBwHqk4gtUgMsYGFSUYfhtnAQ/8TSbaXyS2LX+cQW87LqkvIraWw6o37O24VFBreFoFFXpu3IUeCZfji+Sr4/ykfZuHeMzQbBavyNnHKzPZlbLSXMiucx4/vWzYyOzHeIlbtupXVvbi40V2PieDShaSbjI266kGgFkeCk6z51AaAGebDPtRT1lhBpcoQ6JdF0Yp5VWSnyFARKFtCZ1aEBrlUlrEHLUQY/pFtmDxJQiicRz1YPjR8jRr3C7hlRhWwov0dMocqnMz5209hHGVZWSsaGc9kWjtxREW2ULXfoIwOGbX+WZsyFW2RhXksQPJ5fhyNc4ROkAzUthLb68gC5e0yZHvmLIAU4hcWe0UanJv+jRljn8PAPaJHKFUxQNJyBA7mTbn5mkpycxGrX6T3ZYdPHqvckqt9llJZWjr8NneizzZFRuJk423BDs38fXkvcTAsAckd2Zu0u2KC45WR93sN2/CWrqB7/QU9BsgNdonl/ehAWhU1LbcRRvBTcR9+0wL7vRL7cv5LG3+gRYRKsWI6U2nDSWp0cNpo9+HU0JNiifa5X0cguihqU2bSk6ABozgRtCZ7m+7eqWXMLSzBdmc1CPUoQppo6Wmf6ujdNqI6v2S6pDH781lph8Z2v7ZpxGdhVVPEL51cVn"
} ],
"debug_key": "1234",
"shared_info": "{\"api\":\"shared-storage\",\"report_id\":\"05e3b948-cb8d-4404-be29-bfeac7ad9710\",\"reporting_origin\":\"https://privacy-sandbox-demos-dsp.dev\",\"scheduled_report_time\":\"1707784729\",\"version\":\"0.1\"}"
}
Attribution Reporting API
{
"aggregation_coordinator_origin": "https://publickeyservice.msmt.aws.privacysandboxservices.com",
"aggregation_service_payloads": [ {
"key_id": "2dee0f3f-2aee-4a4a-8238-9154ed3d6f72",
"payload": "pHvTHhcxvNKaCmnLpvYQsXlJpiNRuFO5Zj1QqUlqgWPOfuoHLfiXiFjmpvY8a53/OYnS4bKwHwJReFcofldsu8E9BzTTJ3CEk+B7vbEjnDPaljhpIBMTuQXy3QHGK4slWR/yNZVm2uXRWR/DVVzXziBoTDjN7qaPstRoLKUUMdfY2u8oq4tnLY00Y+NDZttZ4wJvC7hPmvY3lqHjdl14JPD2ytZZ4NViYzno3WKdH/oZc0jhGK4zI38lAM0qpahF/B9yb4zOu7IRIjQpNx73P8naDyddxLldoVlW/qHpO04FguWymscvI/8i6NwUR6Kj8seRlWS0iIUhETt/ai3lilKUHUb+uz0YG2kxjoXq7Ldk+MP56nNl67ZRNi2YZ7bOGI/okYWoT/wt2uWPe/5xAEMmadxl0hQQrG7YXHRSD8rDnaVPXo+AKIxdg727yJeB1ZENZvovl/kIevdRAmdBe2h1U3J6Uz6psly/46fvjgkj5QD+kO2uaYirzvmwS19luJsN/Qvh/R3ZO4qlJIQI0nDJPWwUJ4ODpyVmj4a0xQp3t2ESEnf4EmY7+khn3xpF5+MwEWKES2ZeDf7SHalR99pvZA8G3Fr8M0PWFmT00cmKCBwpQgZyd3Eay70UlqdkbFEedxiCVWKNNOUz41m5KG/7K3aR+dYx57l57Wct4gOFQg3jiUEBJWrFIVCXf12BT5iz5rBQh1N1CUt2oCOhYL/sPuBl6OV5GWHSIj8FUdpoDolqKXWINXfE88MUijE2ghNRpJN25BXIErUQtO9wFQv7zotC6d2BIaF0x8AkKg/7yzBQRySX/FZP3H3lMkpOz9rQMV8DjZ2lz7nV4k6CFo8qhT6cpYJD7GpYl81xJbglNqcJt5Pe5YUHrdBMyAFsTh3yoJvYnhQib/0xVN/a93lbYccxsd0yi375n4Xz0i1HUoe2ps+WlU8XysAUA1agG936eshaY1anTtbJbrcoaH+BNSacKiq4saprgUGl4eDjaR/uBhvUnO52WkmAGon8De3EFMZ/kwpPBNSXi7/MIAMjotsSKBc19bfg"
} ],
"shared_info": "{\"api\":\"attribution-reporting\",\"attribution_destination\":\"https://privacy-sandbox-demos-shop.dev\",\"report_id\":\"5b052748-f5fb-4f14-b291-de03484ed59e\",\"reporting_origin\":\"https://privacy-sandbox-demos-dsp.dev\",\"scheduled_report_time\":\"1707786751\",\"source_registration_time\":\"0\",\"version\":\"0.1\"}",
"source_debug_key": "123456789",
"trigger_debug_key": "123456789"
}
המרת דוחות JSON ל-AVRO
כשמבצעים העלאה של קבצים בקבוצות, דוחות שאפשר לצבור צריכים להיות בפורמט AVRO. כדי ליצור דוח AVRO, תצטרכו את סכימת ה-AVRO של הדוח (AVSC).
קוד JavaScript לדוגמה זמין במאגר GitHub של שירות הצבירה.
בהמשך מופיעה סכימת AVRO לדוחות שניתן לצבירה. השדות השונים בדוחות הם payload, key_id ו-shared_info.
{
"type": "record",
"name": "AggregatableReport",
"fields": [
{
"name": "payload",
"type": "bytes"
},
{
"name": "key_id",
"type": "string"
},
{
"name": "shared_info",
"type": "string"
}
]
}
| פרמטר | סוג | תיאור |
|---|---|---|
payload |
בייטים |
כדי לקבל דוחות של שידורים חיים או של ייצור, צריך לבצע פענוח של מטען הייעודי (payload) בקידוד Base64 ולהמיר אותו למערך בייטים
מ-payload.
|
debug_cleartext_payload |
בייטים |
כדי ליצור דוחות ניפוי באגים, צריך לפענח את מטען הנתונים בקידוד Base64 ולהמיר אותו למערך בייטים
מתוך debug_cleartext_payload.
|
key_id |
מחרוזת | זה יהיה המחרוזת key_id שמופיעה בדוח. המזהה key_id יהיה מזהה ייחודי אוניברסלי דומה באורך 128 ביט. |
shared_info |
מחרוזת | זה יהיה המחרוזת שלא עברה שינוי, שמופיעה בשדה shared_info בדוח. |
זו דוגמה לקובץ JSON של דוח:
{
"aggregation_coordinator_identifier": "aws-cloud",
"aggregation_service_payloads": [{
"debug_cleartext_payload": "omRkYXhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAAAAFWW1vcGVyYX",
"key_id": "3c6e2850-edf6-4886-eb70-eb3f2a7a7596",
"payload": "oapYz92Mb1yam9YQ2AnK8dduTt2RwFUSApGcKqXnG1q+aGXfJ5DGpSxMj0NxdZgp7Cq"
}],
"debug_key": "1234",
"shared_info":
"{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"b029b922-93e9-4d66-a8c6-8cdeec762aed\",\"reporting_origin\":\"https://privacy-sandbox-demos-dsp.dev\",\"scheduled_report_time\":\"1719251997\",\"version\":\"0.1\"}"
}
פלט AVRO של דומיין
כדי ליצור דוחות סיכום באמצעות Aggregation Service, ספקי טכנולוגיית פרסום צריכים את הדוחות עם נתונים שאפשר לצבור ואת קובץ הדומיין. הדוחות שניתן לצבור יהיו דוחות JSON שמתקבלים במקור הדיווח ומומרים לפורמט AVRO. תחומים של פלט יכילו את המפתחות שהוצהרו מראש, שייאספו מהדוחות הניתנים לצירוף וייכתבו בדוחות הסיכום. מידע נוסף על המפתחות האלה בדוחות שיוך ועל המפתחות האלה ב-Private Aggregation API דומיין הפלט יכיל את שדה הסיווג, וערך הסיווג יהיה מפתח הסיווג.
קובץ הדומיין צריך להיות גם בפורמט AVRO לפי הסכימה הבאה:
{
"type": "record",
"name": "AggregationBucket",
"fields": [
{
"name": "bucket",
"type": "bytes",
"doc": "A single bucket that appears in the aggregation service output. 128-bit integer encoded as a 16-byte big-endian bytestring."
}
]
}
מפתח של קטגוריית מפתחות
מפתח הדלי צריך להיות מחרוזת הקסדצימלית של מפתח הדלי. לדוגמה, אם המפתח הוא 1369 בפורמט עשרוני. כשממירים אותו ל-Hex, הוא יהיה 559. לאחר מכן תצטרכו להמיר את הערך 559 למחרוזת בייטים כדי להוסיף אותה ל-AVRO של דומיין הפלט
דוחות באצווה
כדי לקבל מידע נוסף על מכסות פרטיות ועל צירוף נתונים לאצווה, אפשר לעיין במסמך בנושא שיטות לצירוף נתונים לאצווה. בנוסף, חשוב לזכור שאפשר לצרף נתונים לאצווה בדוח ניתן לצירוף רק בתוך פרק זמן מסוים. ההפרש בין תאריך ההתחלה של הדוח (scheduled_report_time) לבין תאריך ההפעלה של אצווה (batch) לא יכול להיות גדול מ-MAX_REPORT_AGE (כרגע 90 ימים).
דוחות סיכום
אחרי שהנתונים נאספים בחבילה, Aggregation Service יוצר את דוח הסיכום בפורמט AVRO. בדוח הסיכום נעשה שימוש בסכימה results.avsc.
דוח הסיכום יופיע ב-output_data_blob_prefix בקטגוריה output_data_bucket_name שצוינה בבקשת createJob.
עבור חבילות של Aggregation Service שבהן מופעל debug_run, נוצרים שני דוחות. דוח הסיכום ודוח הסיכום של ניפוי הבאגים. דוח סיכום הניפוי באגים ימוקם בתיקייה output_data_blob_prefix/debug.
הדוח לניפוי באגים שנוצר משתמש בסכימה debug_results.avsc.
שם דוח הסיכום ודוח הניפוי באגים יהיה [output_data_blob_prefix]-1-of-1.avro. אם הערך של output_data_blob_prefix הוא summary/summary.avro, הדוח יהיה בתיקיית הסיכום עם השם summary-1-of-1.avro.
results.avsc
{
"type": "record",
"name": "AggregatedFact",
"fields": [
{
"name": "bucket",
"type": "bytes",
"doc": "Histogram bucket used in aggregation. 128-bit integer encoded as a 16-byte big-endian bytestring. Leading 0-bits will be left out."
},
{
"name": "metric",
"type": "long",
"doc": "Metric associated with the bucket"
}
]
}
debug_results.avsc
{
"type": "record",
"name": "DebugAggregatedFact",
"fields": [
{
"name": "bucket",
"type": "bytes",
"doc": "Histogram bucket used in aggregation. 128-bit integer encoded as a 16-byte big-endian bytestring. Leading 0-bits will be left out."
},
{
"name": "unnoised_metric",
"type": "long",
"doc": "Unnoised metric associated with the bucket."
},
{
"name": "noise",
"type": "long",
"doc": "The noise applied to the metric in the regular result."
}
{
"name":"annotations",
"type": {
"type": "array",
"items": {
"type":"enum",
"name":"bucket_tags",
"symbols":["in_domain","in_reports"]
}
}
]
}
אחרי ההמרה, דוח הסיכום ייראה כמו בדוגמה results.json. כשמפעילים את debug_run, דוח סיכום ניפוי הבאגים מחזיר תוצאה שדומה לדוגמה debug_results.json.
results.json (דוגמה)
דוחות AVRO שמגיעים מ-Aggregation Service יכולים להיראות דומים, עם מפתח הדלי וערך הסיכום או הערך המצטבר עם רעש נוסף של ערכי הדלי.
{
"bucket": "\u0005Y",
"metric": 26308
}
debug_results.json (example)
דוחות AVRO שמגיעים מ-Aggregation Service אמורים להיראות בערך כמו הדוגמה הבאה, שבה מקבלים את מפתחות הקטגוריה, unnoised_metric (סיכום של מפתחות הקטגוריה ללא רעש) והרעש שנוסף ל-unnoised_metric.
{
"bucket": "\u0005Y",
"unnoised_metric": 128,
"noise": -17948,
"annotations": [
"in_reports",
"in_domain"
]
}
ההערות יכללו גם את התווים in_reports או in_domain, שמשמעותם:
-
in_reports: מפתח המאגר זמין בדוחות המצטברים -
in_domain: מפתח ה-bucket זמין בקובץ ה-AVROoutput_domain