קבלה ואחסון של דוחות שניתן לצבור

כשכלי פרסום דיגיטלי מפעילים ממשקי API למדידת ביצועים (Attribution Reporting API או Private Aggregation API), הדוחות המוצפנים נשלחים מצד הלקוח או הדפדפן של Chrome לנקודת הקצה לדיווח של כלי הפרסום הדיגיטלי, שהיא כתובת URL מסוג .well-known עם מקור הדיווח של כלי הפרסום הדיגיטלי. נקודת הקצה לדיווח מתארחת על ידי ספקי טכנולוגיית הפרסום כדי לאסוף את הדוחות המוצפנים.

תרשים של דוח AgS.
תרשים של דוח AgS

אלה נקודות הקצה לכל 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 Service מתארח באחסון בענן של חברת טכנולוגיית הפרסום, וצריך להיות לו קובץ אימג' ברשימת ההיתרים.

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

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 בייטים כדי לקבל דוחות ניפוי באגים, צריך לבצע פענוח של עומס העבודה ב-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. דומיינים של פלט יכללו את המפתחות שהוצהרו מראש, שייאספו מהדוחות שאפשר לצבור ויכתבו בדוחות הסיכום. מידע נוסף על המפתחות האלה בדוחות שיוך (Attribution) ומידע נוסף על המפתחות ב-Private Aggregation דומיין הפלט יכיל את הקטגוריה של השדה, וערך הקטגוריה יהיה מפתח הקטגוריה.

קובץ הדומיין צריך להיות גם בפורמט 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.

תרשים של מפתח קטגוריה ב-AgS.
תרשים של מפתח קטגוריה ב-AgS.

דוחות באצווה

מידע נוסף על מכסות פרטיות ועל קיבוץ זמין במאמר שיטות קיבוץ. חשוב לזכור שאפשר לקבץ דוחות שניתנים לצבירה רק בתקופה מסוימת. הדוח לא יכול לחרוג מ-MAX_REPORT_AGE בין scheduled_report_time לבין תאריך ההרצה של האצווה (כיום 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 (דוגמה)

דוחות 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: מפתח הקטגוריה זמין בקובץ ה-AVRO ‏output_domain