دریافت & ذخیره گزارش های جمع آوری

هنگامی که فناوری‌های تبلیغاتی APIهای اندازه‌گیری را راه‌اندازی می‌کنند ( API Reporting Attribution یا Private Aggregation API )، گزارش‌های رمزگذاری‌شده از سمت مرورگر Chrome / سمت سرویس گیرنده به نقطه پایانی گزارش فناوری تبلیغات ارسال می‌شوند که یک URL .well-known منشا گزارش فناوری تبلیغات است. نقطه پایانی گزارش توسط فناوری تبلیغات میزبانی می شود تا گزارش های رمزگذاری شده را جمع آوری کند.

نمودار گزارش AgS

نقاط پایانی هر API به شرح زیر است:

  • تجمیع خصوصی

    • اشکال زدایی [reporting-origin]/.well-known/private-aggregation/debug/report-shared-storage
    • زنده [reporting-origin]/.well-known/private-aggregation/report-shared-storage or /.well-known/private-aggregation/report-protected-audience

  • گزارش اسناد

    • اشکال زدایی [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) نیاز دارید.

یک نمونه کد جاوا اسکریپت در مخزن Aggregation Service GitHub موجود است.

شما می توانید 1 فایل AVRO برای همه گزارش های خود داشته باشید یا گزارش ها را به چندین فایل AVRO تقسیم کنید. هیچ محدودیتی در اندازه AVRO وجود ندارد. به دلایل عملکرد، توصیه می شود تعداد فایل های AVRO را بین تعداد CPU های موجود برای نمونه Cloud و 1000 نگه دارید.

در زیر طرحواره 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 بایت ها برای گزارش‌های اشکال‌زدایی، 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

برای تولید گزارش‌های خلاصه با استفاده از سرویس تجمیع، فناوری تبلیغات به گزارش‌های جمع‌آوری‌شده و فایل دامنه نیاز دارد. گزارش‌های جمع‌آوری‌شده، گزارش‌های JSON هستند که در مبدا گزارش‌گیری دریافت شده و به فرمت AVRO تبدیل می‌شوند. دامنه های خروجی حاوی کلیدهای از پیش اعلام شده است که از گزارش های جمع آوری شما جمع آوری می شود و در گزارش های خلاصه نوشته می شود. درباره این کلیدها در گزارش اسناد و کلیدها در تجمیع خصوصی بیشتر بیاموزید. دامنه خروجی شامل سطل فیلد خواهد بود و مقدار سطل کلید سطل شما خواهد بود.

فایل دامنه همچنین باید با فرمت 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 اضافه شود.

نمودار کلید سطل AgS

گزارش های دسته ای

برای درک بیشتر در مورد بودجه های حریم خصوصی و دسته بندی، به سند استراتژی های دسته بندی مراجعه کنید. همچنین، به خاطر داشته باشید که یک گزارش جمع‌آوری‌شده فقط در یک بازه زمانی معین قابل جمع‌آوری است. یک گزارش نباید از MAX_REPORT_AGE بین scheduled_report_time و تاریخ اجرای دسته ای (در حال حاضر 90 روز) تجاوز کند.

گزارش های خلاصه

پس از دسته بندی، Aggregation Service گزارش خلاصه را در قالب AVRO ایجاد می کند. گزارش خلاصه از طرح واره results.avsc استفاده می کند.

گزارش خلاصه در output_data_blob_prefix در سطل output_data_bucket_name بیان شده در درخواست createJob قرار خواهد گرفت.

برای دسته‌های سرویس Aggregation که در آن 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 با نام 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 که از سرویس تجمیع می‌آیند، می‌توانند در جایی که کلید سطل و مقدار خلاصه/تجمیع همراه با نویز اضافه‌شده مقادیر سطل را دارید، مشابه به نظر برسند. 

  {
    "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 : کلید سطل در داخل فایل output_domain AVRO موجود است