Reklam teknolojileri ölçüm API'lerini (Attribution Reporting API veya Private Aggregation API) tetiklediğinde, şifrelenmiş raporlar Chrome tarayıcısından / istemci tarafından reklam teknolojisinin raporlama kaynağını içeren bir .well-known URL'si olan reklam teknolojisinin raporlama uç noktasına gönderilir. Raporlama uç noktası, şifrelenmiş raporları toplamak için reklam teknolojisi tarafından barındırılır.
API başına uç noktalar şunlardır:
Private Aggregation
[reporting-origin]/.well-known/private-aggregation/debug/report-shared-storage'ü hata ayıklama- Canlı
[reporting-origin]/.well-known/private-aggregation/report-shared-storageveya/.well-known/private-aggregation/report-protected-audience
İlişkilendirme Raporları
[reporting-origin]/.well-known/attribution-reporting/debug/report-aggregate-attribution'ü hata ayıklama- Canlı
[reporting-origin]/.well-known/attribution-reporting/report-aggregate-attribution
Reklam teknolojisi uzmanları, raporları bir POST çağrısı üzerinden JSON biçiminde alır. Reklam teknolojileri bu JSON raporlarını toplar ve daha sonra Aggregation Service'te kullanılan AVRO biçimine dönüştürür. Dönüştürülen AVRO raporları, daha sonra toplu olarak işleme alınmaları için reklam teknolojisinin bulut depolama alanında saklanır.
Reklam teknolojisi gruplandırmaya hazır olduğunda, raporların reklam teknolojisinin bulut depolama alanından alındığı toplama hizmeti aracılığıyla bir toplama işi isteği tetikler. Toplama Hizmeti, reklam teknolojisinin bulut depolama alanında barındırılır ve izin verilenler listesinde bir resim olmalıdır.
Alınan raporlar aşağıdakine benzer:
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'u AVRO raporlarına dönüştürme
Toplu işleme sırasında, toplanabilir raporların AVRO biçiminde olması gerekir. AVRO raporu oluşturmak için rapor AVRO şemasına (AVSC) ihtiyacınız vardır.
Aggregation Service GitHub deposunda örnek JavaScript kodu bulunmaktadır.
Aşağıda, toplanabilir raporlar için AVRO şeması verilmiştir. Raporlar için farklı alanlar payload, key_id ve shared_info'dir.
{
"type": "record",
"name": "AggregatableReport",
"fields": [
{
"name": "payload",
"type": "bytes"
},
{
"name": "key_id",
"type": "string"
},
{
"name": "shared_info",
"type": "string"
}
]
}
| Parametre | Tür | Açıklama |
|---|---|---|
payload |
Bayt |
Canlı / üretim raporları için yükün base64 kodunun çözülmesi ve payload'ten bir bayt dizisine dönüştürülmesi gerekir.
|
debug_cleartext_payload |
Bayt |
Hata ayıklama raporları için yükün base64 kodunun çözülmesi ve debug_cleartext_payload'ten bayt dizisine dönüştürülmesi gerekir.
|
key_id |
Dize | Bu, raporda bulunan key_id dizesidir. key_id, benzer şekilde 128 bitlik evrensel olarak benzersiz bir tanımlayıcı olacaktır. |
shared_info |
Dize | Bu, rapordaki shared_info alanında bulunan ve bozulmamış dizedir. |
Aşağıda örnek bir rapor JSON'u verilmiştir:
{
"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\"}"
}
Çıkış Alanı AVRO
Toplama Hizmeti'ni kullanarak özet raporlar oluşturmak için reklam teknolojisinin birleştirilebilir raporlara ve alan dosyasına ihtiyacı vardır. Toplanabilir raporlar, raporlama kaynağında alınan ve AVRO biçimine dönüştürülen JSON raporlarıdır. Çıkış alanları, birleştirilebilir raporlarınızdan toplanıp özet raporlara yazılacak önceden tanımlanmış anahtarları içerir. İlişkilendirme raporlarındaki bu anahtarlar ve Private Aggregation'daki anahtarlar hakkında daha fazla bilgi edinin. Çıkış alanı, alan paketini içerir ve paket değeri, paket anahtarınız olur.
Alan dosyasının da aşağıdaki şemayı kullanan AVRO biçiminde olması gerekir:
{
"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."
}
]
}
Paket Anahtarı
Paket anahtarı, paket anahtarının on altılık bir bayt dizesi olmalıdır. Buna örnek olarak, ondalık olarak 1369 değerine sahip bir anahtar verilebilir. Heksadesimal olarak dönüştürüldüğünde 559 olur. Ardından, 559 değerini çıkış alanına (AVRO) eklenecek bir bayt dizesi biçimine dönüştürmeniz gerekir.
Toplu raporlar
Gizlilik bütçeleri ve gruplandırma hakkında daha fazla bilgi edinmek için gruplandırma stratejileri dokümanlarına gidin. Ayrıca, birleştirilebilir bir raporun yalnızca belirli bir süre içinde gruplandırılabileceğini unutmayın. Rapor, scheduled_report_time ile toplu çalıştırma tarihi arasındaki MAX_REPORT_AGE değerini aşmamalıdır (şu anda 90 gün).
Özet raporlar
Toplama Hizmeti, gruplandırmadan sonra özet raporu AVRO biçiminde oluşturur. Özet raporunda results.avsc şeması kullanılır.
Özet rapor, createJob isteğinde belirtilen output_data_bucket_name paketindeki output_data_blob_prefix içinde yer alır.
debug_run parametresinin etkin olduğu Toplama Hizmeti grupları için iki rapor oluşturur. Özet raporu ve hata ayıklama özeti raporu. Hata ayıklama özet raporu output_data_blob_prefix/debug klasöründe bulunur.
Oluşturulan hata ayıklama raporunda debug_results.avsc şeması kullanılır.
Hem özet hem de hata ayıklama raporu [output_data_blob_prefix]-1-of-1.avro olarak adlandırılır. output_data_blob_prefix değeriniz summary/summary.avro ise rapor, summary-1-of-1.avro adlı özet klasöründe yer alır.
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"]
}
}
]
}
Dönüştürüldükten sonra özet raporunuz results.json örneğine benzer bir görünüme sahip olur. debug_run etkinleştirildiğinde hata ayıklama özeti raporu debug_results.json örneğine benzer bir sonuç döndürür.
results.json (örnek)
Aggregation Service'ten gelen AVRO raporları, grup anahtarının ve grup değerlerinin gürültüsünü içeren özet / toplu değerin bulunduğu benzer bir görünüme sahip olabilir.
{
"bucket": "\u0005Y",
"metric": 26308
}
debug_results.json (örnek)
Aggregation Service'ten gelen hata ayıklama AVRO raporları, paket anahtarlarınızı, unnoised_metric (paket anahtarlarının gürültü içermeyen özeti) ve unnoised_metric'ye eklenen gürültüyü aldığınız aşağıdakine benzer görünmelidir.
{
"bucket": "\u0005Y",
"unnoised_metric": 128,
"noise": -17948,
"annotations": [
"in_reports",
"in_domain"
]
}
Ek açıklamalarda in_reports ve / veya in_domain da yer alır. Bu, şu anlama gelir:
in_reports: Grup anahtarı, toplu raporlarda kullanılabilir.in_domain: Paket anahtarı,output_domainAVRO dosyasında bulunur.