Este guia descreve como os relatórios de medição criptografados são enviados aos provedores de adtech. Os navegadores e clientes do Chrome enviam esses relatórios para endpoints de relatórios designados, onde a plataforma de adtech recebe e armazena relatórios agregáveis. Esses endpoints, localizados em URLs .well-known na origem de relatórios do provedor, são hospedados pela plataforma, permitindo que os provedores de adtech usem a API Attribution Reporting ou a API Private Aggregation para acessá-los.
As etapas a seguir detalham o processo do serviço de agregação para receber e armazenar relatórios agregáveis:
- Quando acionado, o navegador envia relatórios agregáveis com detalhes sobre dados de conversão e entre sites.
- O navegador envia os relatórios criptografados para um URL
.well-knownno domínio de relatórios da adtech. - O sistema encaminha os lotes de relatórios para o serviço de agregação para processamento.
- O serviço de agregação resume os relatórios estatisticamente.
- O serviço de agregação adiciona ruído aos dados resumidos para melhorar a privacidade do usuário.
- O sistema disponibiliza os relatórios à empresa de adtech para fins de análise e medição.
A tabela a seguir descreve os endpoints de depuração e em tempo real da API Private Aggregation e da API Attribution Reporting:
| API | Endpoint | Descrição |
|---|---|---|
| API Private Aggregation |
|
|
| API Attribution Reporting |
|
|
As origens de relatórios recebem relatórios JSON por chamadas POST. Em seguida, o sistema transforma esses relatórios no formato Avro e os coloca no armazenamento em nuvem. Após o processamento em lote, o sistema envia os relatórios do Avro para o serviço de agregação para resumo.
As plataformas de adtech acionam uma solicitação de job de agregação para o serviço de agregação quando um lote de relatórios do Avro está pronto para processamento. Esse serviço, hospedado no ambiente de nuvem da plataforma de adtech, recupera os relatórios Avro necessários do mesmo local de armazenamento. Por motivos de segurança, o serviço de agregação precisa ser configurado para usar uma imagem de contêiner aprovada. Consulte o repositório do GitHub para sandbox de privacidade/serviço de agregação para conferir as imagens de contêiner disponíveis.
Confira a seguir exemplos representativos dos relatórios retornados por cada API:
- Exemplo de relatório da 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\"}"
}
- Exemplo de relatório da 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 JSON em relatórios Avro
Os relatórios agregáveis precisam estar no formato de serialização de dados do Apache Avro para fins de lote. Para criar um relatório do Avro, você precisa usar um esquema AVSC. O arquivo de esquema AVSC define a estrutura e o tipo de dados do registro do Avro. Para conferir um exemplo de esquema AVSC, consulte o arquivo example.avsc neste repositório do GitHub avrodoc/schemata.
Você pode encontrar um exemplo de código JavaScript na seção Collect, transform and batch reports da página Collecting and Batching Aggregatable Reports, localizada no repositório do GitHub privacysandbox/aggregation-service.
Você tem a flexibilidade de armazenar todos os relatórios em um único arquivo AVRO ou distribuí-los em vários arquivos. Embora os arquivos AVRO não tenham limite de tamanho, o desempenho ideal geralmente é alcançado quando o número de arquivos varia de acordo com o número de CPUs na instância da nuvem, até 1.000.
O exemplo de código a seguir mostra um esquema Avro para relatórios agregáveis. Os campos do relatório incluem 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
para relatórios em tempo real ou de produção.
|
debug_cleartext_payload |
Bytes |
O payload precisa ser decodificado em base64 e convertido em uma matriz de bytes
do debug_cleartext_payload para relatórios de depuração.
|
key_id |
String | Esta é a string key_id encontrada no relatório. O key_id é um identificador universalmente exclusivo de 128 bits. |
shared_info |
String | Essa é a string original e não adulterada encontrada no campo shared_info do relatório. |
Confira a seguir um exemplo de relatório 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\"}"
}
Especificação do arquivo de domínio
A geração de relatórios de resumo com o serviço de agregação exige relatórios agregáveis (relatórios JSON convertidos em Avro) e o arquivo de domínio associado. O sistema extrai as chaves predeclaradas dos relatórios agregáveis e as inclui nos relatórios de resumo nos domínios de saída. Confira detalhes sobre essas chaves de agregação importantes em Como entender as chaves de agregação para relatórios de atribuição e na seção Chave de agregação de Noções básicas da API Private Aggregation. O domínio de saída também inclui o campo bucket, que representa o valor da chave do bucket.
O arquivo de domínio 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. It is an 128-bit integer value encoded as a 16-byte big-endian bytestring."
}
]
}
Chave do bucket
A chave do bucket no domínio de saída precisa ser representada como uma string de byte hexadecimal.
Exemplo:
Se a chave do bucket for o valor decimal 1369:
Converta 1369 no equivalente hexadecimal: 559
Converta a string hexadecimal "559" em uma string de bytes.
Essa representação de string de byte da chave do bucket precisa ser incluída no esquema Avro do domínio de saída.
Considerações importantes:
Tipo de dados: a chave do bucket no esquema do Avro precisa ser definida como um tipo de byte para acomodar a representação da string de byte hexadecimal.
Conversão: a conversão de decimal para hexadecimal e, em seguida, para uma string de bytes pode ser implementada usando Python ou Java.
Essa abordagem garante que a chave do bucket seja formatada corretamente e compatível com o tipo de dados esperado no esquema do Avro para o domínio de saída.
Relatórios em lote
Para mais detalhes sobre os orçamentos de privacidade e as estratégias de agrupamento, consulte a documentação sobre estratégias de agrupamento. Os relatórios agregáveis têm um limite de MAX_REPORT_AGE (atualmente 90 dias) entre a scheduled_report_time e a data de execução do lote.
Relatórios de resumo
Após o agrupamento, o serviço de agregação cria o relatório de resumo no formato Avro usando o esquema results.avsc.
Após a conclusão do job, o relatório de resumo é armazenado no output_data_blob_prefix no bucket output_data_bucket_name, conforme especificado na solicitação createJob.
Para lotes do serviço de agregação em que debug_run está ativado, são criados dois relatórios: o de resumo e o de depuração. O relatório de resumo de depuração está localizado na pasta output_data_blob_prefix/debug. O relatório de resumo de depuração usa o esquema debug_results.avsc.
O resumo e o relatório de depuração são nomeados como [output_data_blob_prefix]-1-of-1.avro. Se o output_data_blob_prefix for summary/summary.avro, o relatório estará na pasta de resumo com o nome summary-1-of-1.avro.
Exemplo de results.avsc
Confira a seguir um exemplo de esquema Avro para 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"
}
]
}
O exemplo de esquema Avro define um registro chamado AggregatedFact.
Exemplo de debug_results.avsc
Confira a seguir um exemplo de esquema Avro para 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"]
}
}
]
}
Após a conversão, o relatório de resumo vai ficar parecido com o exemplo results.json. Quando o debug_run está ativado, o retorno do relatório de resumo de depuração é semelhante ao exemplo de debug_results.json.
Formato dos relatórios do Avro
Os relatórios do Avro recebidos do serviço de agregação geralmente seguem um formato consistente. O formato do relatório Avro inclui os seguintes campos:
bucket: um identificador exclusivo para a agregação de dados (por exemplo, "\u0005Y").
métrica: o valor agregado do bucket correspondente. Esse valor geralmente inclui ruídos adicionados para melhorar a privacidade.
Exemplo:
{
"bucket": "\u0005Y",
"metric": 26308
}
Exemplo de debug_results.json
Os relatórios de depuração do Avro do serviço de agregação serão semelhantes ao exemplo de debug_results.json a seguir. Esses relatórios incluem chaves de bucket, o unnoised_metric (resumo das chaves de bucket antes da aplicação do ruído) e o ruído adicionado a essa métrica.
{
"bucket": "\u0005Y",
"unnoised_metric": 128,
"noise": -17948,
"annotations": [
"in_reports",
"in_domain"
]
}
As anotações também contêm os seguintes valores:
in_reports: a chave do bucket disponível nos relatórios agregáveisin_domain: a chave do bucket disponível no arquivo Avrooutput_domain