Quando as adtechs acionam APIs de métricas (API Attribution Reporting ou API Private Aggregation), os relatórios criptografados são enviados do navegador Chrome / lado do cliente para o endpoint de relatórios da adtech, que é um URL .well-known com a origem de relatórios da adtech. O endpoint de geração de relatórios é hospedado pela adtech para coletar os relatórios criptografados.
Confira abaixo os endpoints por API:
Private Aggregation
- Depurar
[reporting-origin]/.well-known/private-aggregation/debug/report-shared-storage [reporting-origin]/.well-known/private-aggregation/report-shared-storageou/.well-known/private-aggregation/report-protected-audienceao vivo
- Depurar
Relatórios de atribuição
- Depurar
[reporting-origin]/.well-known/attribution-reporting/debug/report-aggregate-attribution - Agora
[reporting-origin]/.well-known/attribution-reporting/report-aggregate-attribution
- Depurar
As adtechs vão receber os relatórios em formato JSON por uma chamada POST. As adtechs coletam esses relatórios JSON e os convertem para o formato AVRO, que é usado no serviço de agregação. Depois da conversão, os relatórios AVRO são armazenados no armazenamento em nuvem da adtech para serem agrupados posteriormente.
Quando a adtech estiver pronta para o lote, ela vai acionar uma solicitação de job de agregação pelo serviço de agregação, em que os relatórios são recuperados do armazenamento em nuvem da adtech. O Aggregation Service é hospedado no armazenamento em nuvem da adtech e precisa ter uma imagem na lista de permissões.
Os relatórios recebidos são semelhantes a este:
API Private Aggregation
{
"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 Attribution Reporting
{
"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"
}
Converter relatórios JSON em AVRO
Ao fazer o agrupamento em lotes, os relatórios agregáveis precisam estar no formato AVRO. Para criar um relatório AVRO, você precisa do esquema AVRO do relatório (AVSC).
Um código JavaScript de exemplo está disponível no repositório do Serviço de agregação no GitHub.
Este é o esquema AVRO para relatórios agregáveis. Os diferentes campos dos relatórios são payload, key_id e shared_info.
{
"type": "record",
"name": "AggregatableReport",
"fields": [
{
"name": "payload",
"type": "bytes"
},
{
"name": "key_id",
"type": "string"
},
{
"name": "shared_info",
"type": "string"
}
]
}
| Parâmetro | Tipo | Descrição |
|---|---|---|
payload |
Bytes |
O payload precisa ser decodificado em base64 e convertido em uma matriz de bytes
de payload para relatórios de produção / em tempo real.
|
debug_cleartext_payload |
Bytes |
O payload precisará ser decodificado em base64 e convertido em uma matriz de bytes
de debug_cleartext_payload para relatórios de depuração.
|
key_id |
String | Essa será a string key_id encontrada no relatório. O key_id será um identificador universalmente exclusivo de 128 bits semelhante. |
shared_info |
String | Essa será a string não adulterada encontrada no campo shared_info do relatório. |
Este é um exemplo de JSON de relatório:
{
"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 do domínio de saída
Para gerar relatórios de resumo usando o Serviço de agregação, a adtech precisa dos relatórios agregáveis e do arquivo de domínio. Os relatórios agregáveis serão os relatórios JSON recebidos na origem de relatórios e convertidos para o formato AVRO. Os domínios de saída vão conter as chaves pré-declaradas que serão coletadas dos seus relatórios agregáveis e gravadas nos relatórios de resumo. Saiba mais sobre essas chaves nos relatórios de atribuição e chaves na agregação privada. O domínio de saída vai conter o agrupamento de campos, e o valor do agrupamento será a chave dele.
O arquivo de domínio também precisa estar no formato AVRO usando o seguinte esquema:
{
"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."
}
]
}
Chave do bucket
A chave do bucket precisa ser uma bytestring hexadecimal da chave do bucket. Por exemplo, uma chave de 1369 em decimal. Quando convertido para hexadecimal, ele será 559. Em seguida, você precisará converter 559 em uma bytestring para ser adicionada ao AVRO do domínio de saída.
Relatórios em lote
Para entender melhor os orçamentos de privacidade e o agrupamento em lotes, acesse o documento sobre estratégias de agrupamento em lotes. Além disso, um relatório agregável só pode ser agrupado em lotes dentro de um determinado período. Um relatório não pode exceder o MAX_REPORT_AGE entre a scheduled_report_time e a data de execução do lote (atualmente 90 dias).
Relatórios de resumo
Depois do agrupamento em lotes, o serviço de agregação cria o relatório de resumo no formato AVRO. O relatório de resumo usa o esquema results.avsc.
O relatório de resumo vai estar em output_data_blob_prefix no bucket output_data_bucket_name indicado na solicitação createJob.
Para lotes do serviço de agregação em que debug_run está ativado, ele cria dois relatórios. O relatório de resumo e o relatório de resumo de depuração. O relatório de resumo de depuração vai estar na pasta output_data_blob_prefix/debug.
O relatório de depuração gerado usa o esquema debug_results.avsc.
Os relatórios de resumo e de depuração serão nomeados como [output_data_blob_prefix]-1-of-1.avro. Se o output_data_blob_prefix for summary/summary.avro, o relatório vai estar na pasta de resumo com o nome 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"]
}
}
]
}
Depois da conversão, o relatório de resumo vai ficar parecido com o exemplo results.json. Quando "debug_run" está ativado, o relatório de resumo de depuração retorna algo semelhante ao exemplo debug_results.json.
results.json (exemplo)
Os relatórios AVRO do Aggregation Service podem parecer semelhantes quando você tem a chave de agrupamento e o valor de resumo / agregação com ruído adicionado aos valores de agrupamento.
{
"bucket": "\u0005Y",
"metric": 26308
}
debug_results.json (exemplo)
Os relatórios AVRO de depuração do Aggregation Service devem ser semelhantes ao seguinte, em que você recebe as chaves de bucket, unnoised_metric (resumo das chaves de bucket sem ruído) e o ruído adicionado ao unnoised_metric.
{
"bucket": "\u0005Y",
"unnoised_metric": 128,
"noise": -17948,
"annotations": [
"in_reports",
"in_domain"
]
}
As anotações também vão conter in_reports e / ou in_domain, o que significa:
in_reports: a chave do bucket está disponível nos relatórios agregáveis.in_domain: a chave do bucket está disponível no arquivo AVROoutput_domain