כשטכנולוגיות פרסום מפעילות ממשקי API למדידת ביצועים (Attribution Reporting API או Private Aggregation API), הדוחות המוצפנים נשלחים מצד הלקוח או הדפדפן של Chrome לנקודת הקצה לדיווח של טכנולוגיית הפרסום, שהיא כתובת URL מסוג .well-known עם מקור הדיווח של טכנולוגיית הפרסום. חברת AdTech מארחת את נקודת הקצה לדיווח כדי לאסוף את הדוחות המוצפנים.
אלה נקודות הקצה לכל 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 נשמרים באחסון בענן של פלטפורמת טכנולוגיית הפרסום, כדי שאפשר יהיה לקבץ אותם מאוחר יותר.
כשטכנולוגיית הפרסום תהיה מוכנה לאיסוף נתונים באצווה, היא תפעיל בקשה לביצוע משימת צבירת נתונים דרך שירות הצבירת הנתונים, שבו הדוחות מאוחזרים מאחסון הענן של טכנולוגיית הפרסום. שירות האגרגציה מתארח באחסון בענן של חברת טכנולוגיית הפרסום, וצריך להיות לו קובץ אימג' ברשימת ההיתרים.
הדוחות שהתקבלו נראים כך:
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 של Aggregation Service.
זוהי הסכימה של 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 |
בייטים |
כדי לקבל דוחות פעילים או דוחות ייצור, תצטרכו לבצע פענוח של עומס העבודה לפי base64 ולהמיר אותו למערך בייטים מ-payload.
|
debug_cleartext_payload |
בייטים |
כדי לקבל דוחות ניפוי באגים, תצטרכו לפענח את עומס העבודה (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
כדי ליצור דוחות סיכום באמצעות שירות הצבירה, ל-AdTech נדרשים הדוחות שאפשר לצבור ואת קובץ הדומיין. הדוחות שאפשר לצבור יהיו דוחות ה-JSON שהתקבלו במקור הדיווח והומרו לפורמט AVRO. דומיינים של פלט יכללו את המפתחות שהוצהרו מראש, שייאספו מהדוחות שאפשר לצבור ויוכתבו בדוחות הסיכום. מידע נוסף על המפתחות האלה זמין בדוחות שיוך (Attribution) ובדוחות על צבירת נתונים פרטית. דומיין הפלט יכיל את הקטגוריה של השדה, וערך הקטגוריה יהיה מפתח הקטגוריה.
קובץ הדומיין צריך להיות גם בפורמט 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."
}
]
}
מפתח קטגוריה
מפתח הקטגוריה צריך להיות מחרוזת בייטים של 16 ביט של מפתח הקטגוריה. דוגמה לכך היא מפתח של 1369 בספרות עשרוניות. אחרי ההמרה ל-Hex, הערך יהיה 559. לאחר מכן צריך להמיר את הערך 559 למחרוזת בייט כדי להוסיף אותו לדומיין הפלט AVRO.
דוחות באצווה
מידע נוסף על תקציבי פרטיות ועל קיבוץ זמין במאמר שיטות קיבוץ. חשוב לזכור שאפשר לקבץ דוחות שניתנים לצבירה רק בתקופה מסוימת. הדוח לא יכול לחרוג מ-MAX_REPORT_AGE בין scheduled_report_time לבין תאריך ההרצה של האצווה (כיום 90 יום).
דוחות סיכום
אחרי הקיבוץ, Aggregation Service יוצר את דוח הסיכום בפורמט AVRO. בדוח הסיכום נעשה שימוש בסכימה results.avsc.
דוח הסיכום יופיע ב-output_data_blob_prefix בקטגוריה output_data_bucket_name שצוינה בבקשה createJob.
באצווה של שירות צבירה שבה הפונקציה debug_run מופעלת, נוצרים שני דוחות. דוח הסיכום ודוח הסיכום של ניפוי הבאגים. דוח הסיכום של ניפוי הבאגים ימוקם בתיקייה output_data_blob_prefix/debug.
תבנית ה-schema שמשמשת את דוח ניפוי הבאגים שנוצר היא 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 (דוגמה)
דוחות 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: מפתח הקטגוריה זמין בקובץ ה-AVROoutput_domain