คู่มือนี้จะอธิบายวิธีส่งรายงานการวัดผลที่เข้ารหัสไปยังผู้ให้บริการเทคโนโลยีโฆษณา เบราว์เซอร์ Chrome และไคลเอ็นต์จะส่งรายงานเหล่านี้ไปยังปลายทางการรายงานที่กําหนด ซึ่งแพลตฟอร์มเทคโนโลยีโฆษณาจะรับและจัดเก็บรายงานที่รวบรวมได้ ปลายทางเหล่านี้อยู่ที่ .well-known URL ภายในต้นทางการรายงานของผู้ให้บริการ ซึ่งโฮสต์โดยแพลตฟอร์ม ช่วยให้ผู้ให้บริการด้านเทคโนโลยีโฆษณาที่ใช้ Attribution Reporting API หรือ Private Aggregation API สามารถเข้าถึงได้
ขั้นตอนต่อไปนี้แสดงรายละเอียดกระบวนการของบริการรวบรวมข้อมูลในการรับและจัดเก็บรายงานที่รวบรวมได้
- เมื่อทริกเกอร์ เบราว์เซอร์จะส่งรายงานที่รวบรวมได้ซึ่งมีรายละเอียดเกี่ยวกับทั้งข้อมูลข้ามเว็บไซต์และข้อมูล Conversion
- เบราว์เซอร์จะส่งรายงานที่เข้ารหัสไปยัง
.well-knownURL ภายในโดเมนการรายงานเทคโนโลยีโฆษณา - ระบบจะส่งต่อรายงานกลุ่มไปยังบริการรวบรวมข้อมูลเพื่อประมวลผล
- บริการรวบรวมข้อมูลจะสรุปรายงานเป็นสถิติ
- บริการรวบรวมข้อมูลจะเพิ่มสัญญาณรบกวนลงในข้อมูลที่สรุปเพื่อเพิ่มความเป็นส่วนตัวของผู้ใช้
- ระบบจะทําให้บริษัทเทคโนโลยีโฆษณาเข้าถึงรายงานได้เพื่อวัตถุประสงค์ในการวิเคราะห์และการวัดผล
ตารางต่อไปนี้อธิบายปลายทางที่ใช้แก้ไขข้อบกพร่องและปลายทางเวอร์ชันที่ใช้งานจริงสําหรับ Private Aggregation API และ Attribution Reporting API
| API | ปลายทาง | คำอธิบาย |
|---|---|---|
| Private Aggregation API |
|
|
| Attribution Reporting API |
|
|
ต้นทางการรายงานจะได้รับรายงาน JSON ผ่านการเรียกใช้ POST จากนั้นระบบจะเปลี่ยนรูปแบบรายงานเหล่านี้เป็น Avro และจัดเก็บไว้ในระบบพื้นที่เก็บข้อมูลบนระบบคลาวด์ หลังจากการประมวลผลเป็นกลุ่มแล้ว ระบบจะส่งรายงาน Avro ไปยังบริการรวบรวมข้อมูลเพื่อสรุป
แพลตฟอร์มเทคโนโลยีโฆษณาจะทริกเกอร์คําของานการรวมไปยังบริการการรวมเมื่อรายงาน Avro หลายรายการพร้อมสําหรับการประมวลผล บริการนี้ซึ่งโฮสต์ภายในสภาพแวดล้อมระบบคลาวด์ของแพลตฟอร์มเทคโนโลยีโฆษณาจะดึงข้อมูลรายงาน Avro ที่จําเป็นจากตำแหน่งพื้นที่เก็บข้อมูลเดียวกัน คุณต้องกําหนดค่าบริการรวบรวมข้อมูลให้ใช้อิมเมจคอนเทนเนอร์ที่ได้รับอนุมัติเพื่อความปลอดภัย ดูอิมเมจคอนเทนเนอร์ที่ใช้ได้ได้ที่ที่เก็บ GitHub ของ Privacy Sandbox/บริการรวบรวมข้อมูล
ตัวอย่างต่อไปนี้แสดงตัวอย่างรายงานที่แสดงผลโดย API แต่ละรายการ
- ตัวอย่างรายงาน 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
รายงานที่รวบรวมได้ต้องอยู่ในรูปแบบการจัดรูปแบบข้อมูล Apache Avro เพื่อวัตถุประสงค์ในการแบ่งกลุ่ม หากต้องการสร้างรายงาน Avro คุณต้องใช้สคีมา AVSC ไฟล์สคีมา AVSC จะกําหนดโครงสร้างระเบียนและประเภทข้อมูล Avro ดูตัวอย่างสคีมา AVSC ได้ที่ไฟล์ example.avsc ในที่เก็บ GitHub ของ avrodoc/schemata
คุณดูตัวอย่างโค้ด JavaScript ได้ในส่วนรวบรวม เปลี่ยนรูปแบบ และจัดกลุ่มรายงานของหน้าการรวบรวมและการจัดกลุ่มรายงานที่รวบรวมได้ซึ่งอยู่ในที่เก็บ GitHub ของ privacysandbox/aggregation-service
คุณมีความยืดหยุ่นในการจัดเก็บรายงานทั้งหมดในไฟล์ AVRO ไฟล์เดียวหรือจัดเก็บไว้ในหลายไฟล์ก็ได้ แม้ว่าไฟล์ AVRO จะไม่มีขีดจำกัดด้านขนาด แต่โดยทั่วไปแล้วประสิทธิภาพที่ดีที่สุดจะเกิดขึ้นเมื่อจำนวนไฟล์อยู่ในช่วงตั้งแต่จำนวน CPU ในอินสแตนซ์ระบบคลาวด์ของคุณไปจนถึง 1, 000 ไฟล์
ตัวอย่างโค้ดต่อไปนี้แสดงสคีมา 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 และแปลงเป็นอาร์เรย์ไบต์สำหรับรายงานเวอร์ชันที่ใช้จริงหรือเวอร์ชันที่เผยแพร่
|
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\"}"
}
ข้อกําหนดของไฟล์โดเมน
การสร้างรายงานสรุปด้วยบริการรวบรวมข้อมูลต้องใช้รายงานที่รวบรวมได้ (รายงาน JSON ที่แปลงเป็น Avro) และไฟล์โดเมนที่เชื่อมโยง ระบบจะดึงข้อมูลคีย์ที่ประกาศไว้ล่วงหน้าจากรายงานที่รวบรวมได้ และรวมไว้ในรายงานสรุปภายในโดเมนเอาต์พุต คุณดูรายละเอียดเกี่ยวกับคีย์การรวมข้อมูลสําคัญเหล่านี้ได้ในการทำความเข้าใจคีย์การรวมข้อมูลสําหรับการรายงานการระบุแหล่งที่มา และส่วนคีย์การรวมข้อมูลของข้อมูลพื้นฐานเกี่ยวกับ Private Aggregation API โดเมนเอาต์พุตยังมีช่อง bucket ซึ่งแสดงค่าคีย์ของที่เก็บข้อมูลด้วย
ไฟล์โดเมนต้องอยู่ในรูปแบบ Avro โดยใช้สคีมาต่อไปนี้
{
"type": "record",
"name": "AggregationBucket",
"fields": [
{
"name": "bucket",
"type": "bytes",
"doc": "A single bucket that appears in the aggregation service output. It is an 128-bit integer value encoded as a 16-byte big-endian bytestring."
}
]
}
คีย์ที่เก็บข้อมูล
คีย์ที่เก็บข้อมูลภายในโดเมนเอาต์พุตต้องแสดงเป็นสตริงไบต์ฐาน 16
เช่น
หากคีย์ที่เก็บข้อมูลเป็นค่าทศนิยม 1369
แปลง 1369 เป็นค่าฐานสิบหกที่เทียบเท่า: 559
แปลงสตริงฐานสิบหก "559" เป็นสตริงไบต์
จากนั้นควรรวมการแสดงสตริงไบต์ของคีย์ที่เก็บข้อมูลนี้ไว้ในสคีมา Avro ของโดเมนเอาต์พุต
สิ่งสำคัญที่ต้องคำนึงถึง
ประเภทข้อมูล: ควรกำหนดคีย์ที่เก็บข้อมูลภายในสคีมา Avro เป็นประเภทไบต์เพื่อให้รองรับการแสดงสตริงไบต์ฐาน 16
การแปลง: สามารถใช้ Python หรือ Java เพื่อแปลงทศนิยมเป็นฐาน 16 แล้วแปลงเป็นสตริงไบต์
วิธีนี้ช่วยให้มั่นใจว่าคีย์ที่เก็บข้อมูลอยู่ในรูปแบบที่ถูกต้องและเข้ากันได้กับประเภทข้อมูลที่คาดไว้ภายในสคีมา Avro สำหรับโดเมนเอาต์พุต
รายงานกลุ่ม
ดูรายละเอียดเกี่ยวกับงบประมาณความเป็นส่วนตัวและกลยุทธ์การแบ่งกลุ่มได้ในเอกสารประกอบเกี่ยวกับกลยุทธ์การแบ่งกลุ่ม โปรดทราบว่ารายงานที่รวบรวมได้จะมีขีดจํากัด MAX_REPORT_AGE (ปัจจุบันคือ 90 วัน) ระหว่าง scheduled_report_time กับวันที่เรียกใช้กลุ่ม
รายงานสรุป
หลังจากจัดกลุ่มแล้ว บริการรวบรวมข้อมูลจะสร้างรายงานสรุปในรูปแบบ Avro โดยใช้สคีมา results.avsc
เมื่องานเสร็จสมบูรณ์แล้ว ระบบจะจัดเก็บรายงานสรุปใน output_data_blob_prefix ภายในที่เก็บข้อมูล output_data_bucket_name ตามที่ระบุไว้ในคําขอ createJob
สําหรับกลุ่มบริการรวบรวมข้อมูลที่มีการเปิดใช้ debug_run ระบบจะสร้างรายงาน 2 ฉบับ ได้แก่ รายงานสรุปและรายงานสรุปการแก้ไขข้อบกพร่อง รายงานสรุปการแก้ไขข้อบกพร่องอยู่ในโฟลเดอร์ 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
ต่อไปนี้คือตัวอย่างสคีมา Avro สำหรับ results.avsc
{
"type": "record",
"name": "AggregatedFact",
"fields": [
{
"name": "bucket",
"type": "bytes",
"doc": "Histogram bucket used in aggregation. It is an 128-bit integer value encoded as a 16-byte big-endian bytestring. Leading 0-bits are left out."
},
{
"name": "metric",
"type": "long",
"doc": "The metric associated with the bucket"
}
]
}
ตัวอย่างสคีมา Avro กําหนดระเบียนชื่อ AggregatedFact
ตัวอย่าง debug_results.avsc
ต่อไปนี้คือตัวอย่างสคีมา Avro สําหรับ debug_results.avsc
{
"type": "record",
"name": "DebugAggregatedFact", Output domains include summary reports that contain pre-declared keys extracted from your aggregatable reports.
"fields": [
{
"name": "bucket",
"type": "bytes",
"doc": "This represents the histogram bucket used in aggregation. It's a 128-bit integer, encoded as a 16-byte big-endian bytestring, with leading zero bytes omitted.."
},
{
"name": "unnoised_metric",
"type": "long",
"doc": "The raw metric for 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ตัวอย่าง
รูปแบบรายงาน Avro
โดยทั่วไปแล้ว รายงาน Avro ที่ได้รับจากบริการรวบรวมข้อมูลจะเป็นไปตามรูปแบบที่สอดคล้องกัน รูปแบบรายงาน Avro มีช่องต่อไปนี้
ที่เก็บข้อมูล: ตัวระบุที่ไม่ซ้ำกันสำหรับการรวบรวมข้อมูล (เช่น "\u0005Y")
metric: ค่ารวมของที่เก็บข้อมูลที่เกี่ยวข้อง ค่านี้มักจะมีสัญญาณรบกวนเพิ่มเติมเพื่อเพิ่มความเป็นส่วนตัว
เช่น
{
"bucket": "\u0005Y",
"metric": 26308
}
ตัวอย่าง debug_results.json
รายงาน Avro ที่ใช้แก้ไขข้อบกพร่องจากบริการการรวมข้อมูลจะมีลักษณะคล้ายกับตัวอย่าง debug_results.json ต่อไปนี้ รายงานเหล่านี้ประกอบด้วยคีย์ที่เก็บข้อมูล unnoised_metric (สรุปของคีย์ที่เก็บข้อมูลก่อนใช้สัญญาณรบกวน) และสัญญาณรบกวนซึ่งเพิ่มลงในเมตริกนั้น
{
"bucket": "\u0005Y",
"unnoised_metric": 128,
"noise": -17948,
"annotations": [
"in_reports",
"in_domain"
]
}
คําอธิบายประกอบยังมีค่าต่อไปนี้ด้วย
in_reports: คีย์ที่เก็บข้อมูลที่มีอยู่ในรายงานที่รวบรวมได้in_domain: รหัสที่เก็บข้อมูลที่มีอยู่ในไฟล์ Avrooutput_domain