Когда рекламные специалисты активируют API-интерфейсы измерения ( API отчетов об атрибуции или API частной агрегации ), зашифрованные отчеты отправляются со стороны браузера/клиента Chrome на конечную точку отчетов рекламных технологий, которая представляет собой .well-known URL-адрес с источником отчетов рекламной технологии. Конечная точка отчетов размещается рекламной технологией для сбора зашифрованных отчетов .
Ниже приведены конечные точки для каждого API:
Частная агрегация
- Отладка
[reporting-origin]/.well-known/private-aggregation/debug/report-shared-storage - Live
[reporting-origin]/.well-known/private-aggregation/report-shared-storageили/.well-known/private-aggregation/report-protected-audience
- Отладка
Отчеты по атрибуции
- Отладка
[reporting-origin]/.well-known/attribution-reporting/debug/report-aggregate-attribution - Live
[reporting-origin]/.well-known/attribution-reporting/report-aggregate-attribution
- Отладка
Рекламные специалисты будут получать отчеты в формате JSON посредством вызова POST. Специалисты по рекламе соберут эти отчеты JSON, а затем преобразуют их в формат AVRO, который используется в службе агрегирования. После преобразования отчеты AVRO сохраняются в облачном хранилище рекламной технологии для последующей пакетной обработки.
Как только рекламная технология будет готова к пакетной обработке, она инициирует запрос задания на агрегацию через службу агрегации, где отчеты извлекаются из облачного хранилища рекламной технологии. Служба агрегации размещается в облачном хранилище рекламной компании и должна иметь изображение, включенное в список разрешенных .
Полученные отчеты выглядят примерно так:
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\"}"
}
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 службы агрегирования.
Вы можете использовать один файл AVRO для всех ваших отчетов или разделить отчеты на несколько файлов AVRO. Ограничений на размер AVRO нет. Из соображений производительности рекомендуется поддерживать количество файлов AVRO в диапазоне от количества процессоров, доступных для вашего облачного экземпляра, до 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 | Байты | Полезную нагрузку необходимо будет декодировать в формате 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
Для создания сводных отчетов с помощью службы агрегирования рекламной технологии требуются агрегированные отчеты и файл домена. Агрегированные отчеты будут представлять собой отчеты в формате JSON, полученные в источнике отчетов и преобразованные в формат AVRO. Выходные домены будут содержать предварительно объявленные ключи, которые будут собираться из ваших агрегируемых отчетов и записываться в сводные отчеты. Узнайте больше об этих ключах в отчетах по атрибуции и ключах в 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."
}
]
}
Ключ от ведра
Ключ сегмента должен представлять собой шестнадцатеричную байтовую строку ключа сегмента. Примером этого может быть ключ 1369 в десятичной системе счисления. При преобразовании в Hex это будет 559. Затем вам нужно будет преобразовать 559 в байтовую строку, которая будет добавлена в выходной домен AVRO.
Пакетные отчеты
Чтобы узнать больше о бюджетах конфиденциальности и пакетной обработке, перейдите к документу по стратегиям пакетной обработки . Также имейте в виду, что агрегированный отчет можно группировать только в течение определенного периода времени. Отчет не должен превышать MAX_REPORT_AGE между scheduled_report_time и датой выполнения пакета (в настоящее время 90 дней).
Сводные отчеты
После пакетной обработки служба агрегации создает сводный отчет в формате AVRO. В сводном отчете используется схема results.avsc .
Сводный отчет будет расположен в префиксе output_data_blob_prefix в сегменте output_data_bucket_name , указанном в запросе createJob .
Для пакетов службы агрегации, в которых включен 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 .
результаты.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 .
результаты.json (пример)
Отчеты AVRO, поступающие из службы агрегирования, могут выглядеть аналогично, если у вас есть ключ сегмента и сводное/агрегированное значение с добавленным шумом значений сегмента.
{
"bucket": "\u0005Y",
"metric": 26308
}
debug_results.json (пример)
Отчеты AVRO об отладке, поступающие из службы агрегации, должны выглядеть примерно так, как показано ниже: вы получаете ключи сегмента, unnoised_metric (сводка ключей сегмента без шума) и шум, который добавляется к unnoised_metric .
{
"bucket": "\u0005Y",
"unnoised_metric": 128,
"noise": -17948,
"annotations": [
"in_reports",
"in_domain"
]
}
Аннотации также будут содержать in_reports и/или in_domain , что означает:
-
in_reports: ключ сегмента доступен внутри агрегированных отчетов. -
in_domain: ключ сегмента доступен внутри файла AVROoutput_domain