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 uç noktasına gönderilir. Bu uç nokta, reklam teknolojisinin raporlama kaynağını içeren bir .well-known URL'sidir. 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öğesini 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öğesini 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ı toplayıp daha sonra toplama hizmetinde 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 içermelidir.
Alınan raporlar aşağıdaki gibi görünür:
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 mevcuttur.
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
Reklam teknolojisinin, toplama hizmetini kullanarak özet raporlar oluşturması için birleştirilebilir raporlar ve alan adı dosyası gerekir. Toplanabilir raporlar, raporlama kaynağında alınan ve AVRO biçimine dönüştürülen JSON raporları olacaktı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 özel toplamadaki 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 belgesine 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)
Toplama Hizmeti'nden gelen AVRO raporları, paket anahtarına ve paket değerlerinin gürültüsünü içeren özet / toplama değerine sahip olduğunuz benzer bir görünüme sahip olabilir.
{
"bucket": "\u0005Y",
"metric": 26308
}
debug_results.json (örnek)
Toplama Hizmeti'nden gelen hata ayıklama AVRO raporları, paket anahtarlarınızı, unnoised_metric'yi (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.