1. Pré-requisitos
Para executar este codelab, é preciso cumprir alguns pré-requisitos. Cada requisito é marcado conforme necessário para "Teste local" ou "Serviço de agregação".
1.1. Fazer o download da Ferramenta de teste local
Para realizar testes locais, é necessário fazer o download da Ferramenta de teste local. A ferramenta vai gerar relatórios resumidos com base nos relatórios de depuração não criptografados.
A ferramenta de teste local está disponível para download nos arquivos JAR do Lambda no GitHub. Ele precisa ter o nome LocalTestingTool_{version}.jar.
1.2. Verifique se o JAVA JRE está instalado (serviço de agregação e teste local)
Abra o Terminal e use java --version para verificar se a máquina tem o Java ou o openJDK instalado.
Se ele não estiver instalado, faça o download e instale-o no site do Java ou no site do openJDK (link em inglês).
1.3. Baixar o conversor de relatórios agregáveis (teste local e serviço de agregação)
Faça o download de uma cópia do conversor de relatórios agregáveis no repositório do GitHub para demonstrações do Sandbox de privacidade (link em inglês).
1.4. Ativar as APIs do Sandbox de privacidade (teste local e serviço de agregação)
No navegador, acesse chrome://flags/#privacy-sandbox-ads-apis e ative as APIs do Sandbox de privacidade.
Verifique se os cookies de terceiros estão ativados.
No navegador, acesse chrome://settings/cookies e selecione Bloquear cookies de terceiros no modo de navegação anônima.
1.5. Inscrição na Web e no Android (serviço de agregação)
Para usar as APIs do Sandbox de privacidade em um ambiente de produção, confira se você concluiu o registro e o atestado para o Chrome e o Android.
Para testes locais, o registro pode ser desativado usando uma sinalização do Chrome e um interruptor da CLI.
Para usar a sinalização do Chrome na nossa demonstração, acesse chrome://flags/#privacy-sandbox-enrollment-overrides e atualize a substituição no seu site. Se você for usar nosso site de demonstração, não precisa fazer nenhuma atualização.
1.6. Integração do serviço de agregação (serviço de agregação)
O serviço de agregação requer integração aos coordenadores para que eles possam usar o serviço. Preencha o formulário de integração do serviço de agregação (link em inglês) fornecendo o endereço do site do relatório, o ID da conta da AWS e outras informações.
1,7. Provedor de nuvem (serviço de agregação)
O serviço de agregação requer o uso de um ambiente de execução confiável que usa um ambiente em nuvem. O serviço de agregação é compatível com Amazon Web Services (AWS) e Google Cloud (GCP). Este codelab aborda apenas a integração com a AWS.
A AWS oferece um ambiente de execução confiável chamado Nitro Enclaves. Verifique se você tem uma conta da AWS e siga as instruções de instalação e atualização da AWS CLI para configurar o ambiente da AWS CLI.
Se a CLI da AWS for nova, configure a CLI da AWS usando as instruções de configuração da CLI.
1.7.1. Criar o bucket S3 da AWS
Crie um bucket S3 da AWS para armazenar o estado do Terraform e outro bucket do S3 para armazenar seus relatórios e relatórios de resumo. É possível usar o comando da CLI fornecido. Substitua o campo em <> pelas variáveis adequadas.
aws s3api create-bucket --bucket <tf_bucket_name> --region us-east-1
aws s3api create-bucket --bucket <report_bucket_name> --region us-east-1
1.7.2. Criar chave de acesso do usuário
Crie chaves de acesso do usuário com o guia da AWS. Ele será usado para chamar os endpoints de API createJob e getJob criados na AWS.
1.7.3. Permissões de usuário e grupo da AWS
Para implantar o serviço de agregação na AWS, você precisará conceder determinadas permissões ao usuário usado na implantação do serviço. Para este codelab, o usuário precisa ter acesso de administrador para garantir permissões completas na implantação.
1,8. Terraform (serviço de agregação)
Este codelab usa o Terraform para implantar o serviço de agregação. Confira se o binário do Terraform está instalado no seu ambiente local.
Faça o download do binário do Terraform para o ambiente local.
Depois de fazer o download do binário do Terraform, extraia o arquivo e mova-o para /usr/local/bin.
cp <directory>/terraform /usr/local/bin
Verifique se o Terraform está disponível no caminho de classe.
terraform -v
1,9. Postman (para serviço de agregação AWS)
Neste codelab, use o Postman para gerenciar as solicitações.
Para criar um espaço de trabalho, acesse Espaços de trabalho, na parte de cima, e selecione Criar espaço de trabalho.
Selecione Espaço de trabalho em branco, clique em "Próxima" e nomeie-o como Sandbox de privacidade. Selecione Pessoal e clique em Criar.
Faça o download dos arquivos pré-configurados da configuração JSON e do ambiente global do espaço de trabalho.
Importe os arquivos JSON para o Meu espaço de trabalho usando o botão Importar.
Isso vai criar a coleção do Sandbox de privacidade com as solicitações HTTP createJob e getJob.
Atualize a "Chave de acesso" e a "Chave secreta" da AWS por meio da "Visão rápida do ambiente".
Clique em "Editar" e atualize o "Valor atual" de access_key e secret_key. Observe que frontend_api_id será fornecido na seção 3.1.4 deste documento. Recomendamos usar a região us-east-1. No entanto, se você quiser implantar em uma região diferente, copie a AMI lançada na sua conta ou faça uma criação automática usando os scripts fornecidos.
2. Codelab de testes locais
Você pode usar a ferramenta de teste local na sua máquina para agregar e gerar relatórios de resumo com os relatórios de depuração não criptografados.
Etapas do codelab
Etapa 2.1. Acionar relatório: acione o relatório de agregação privada para coletar o relatório.
Etapa 2.2. Criar relatório agregável de depuração: converta o relatório JSON coletado em um formato formatado pelo AVRO.
Essa etapa será semelhante a quando as adtechs coletam os relatórios dos endpoints de relatórios da API e convertem os relatórios JSON em relatórios no formato AVRO.
Etapa 2.3. Analisar a chave do intervalo do relatório de depuração: as chaves de intervalo são projetadas por adtechs. Neste codelab, como os buckets são predefinidos, recupere as chaves de bucket conforme fornecidas.
Etapa 2.4. Crie o domínio de saída AVRO: depois que as chaves de intervalo forem recuperadas, crie o arquivo AVRO do domínio de saída.
Etapa 2.5. Crie relatórios de resumo usando a Ferramenta de teste local: use essa ferramenta para gerar relatórios de resumo no ambiente local.
Etapa 2.6. Analisar o relatório de resumo: consulte o relatório de resumo criado pela Ferramenta de teste local.
2.1. Acionar relatório
Acesse o site de demonstração do Sandbox de privacidade. Isso aciona um relatório de agregação particular. Confira o relatório em chrome://private-aggregation-internals.
Caso seu relatório tenha o status Pendente, selecione-o e clique em Enviar relatórios selecionados.
2.2. Criar relatório agregável de depuração
Em chrome://private-aggregation-internals, copie o "Corpo do relatório" recebido no endpoint [reporting-origin]/.well-known/private-aggregation/report-shared-storage.
Verifique se em "Corpo do relatório" o aggregation_coordinator_origin contém https://publickeyservice.msmt.aws.privacysandboxservices.com, o que significa que é um relatório agregável da AWS.
Coloque o "Corpo do relatório" JSON em um arquivo JSON. Neste exemplo, você pode usar o vim. Mas você pode usar o editor de texto que quiser.
vim report.json
Cole o relatório em report.json e salve o arquivo.
Depois, navegue até a pasta do relatório e use aggregatable_report_converter.jar para criar o relatório agregável de depuração. Isso cria um relatório agregável chamado report.avro no diretório atual.
java -jar aggregatable_report_converter.jar \
--request_type convertToAvro \
--input_file report.json \
--debug
2.3. Analisar a chave do bucket do relatório de depuração
O serviço de agregação requer dois arquivos em lotes. O relatório agregável e o arquivo de domínio de saída. O arquivo de domínio de saída contém as chaves que você quer recuperar dos relatórios agregáveis. Para criar o arquivo output_domain.avro, você precisa das chaves de bucket que podem ser recuperadas dos relatórios.
As chaves de bucket são projetadas pelo autor da chamada da API, e a demonstração contém chaves de bucket de exemplo pré-construídas. Como a demonstração ativou o modo de depuração para a agregação privada, você pode analisar o payload de texto não criptografado de depuração do "Corpo do relatório" para recuperar a chave do bucket. No entanto, nesse caso, a demonstração do Sandbox de privacidade do site cria as chaves do bucket. Como a agregação particular desse site está no modo de depuração, é possível usar o debug_cleartext_payload do Corpo do relatório para conseguir a chave do bucket.
Copie o debug_cleartext_payload do corpo do relatório.
Abra a ferramenta Decodificador de payload de depuração para Agregação Privada, cole o debug_cleartext_payload na caixa INPUT e clique em INPUT.
A página retorna o valor decimal da chave do bucket. Confira a seguir um exemplo de chave de bucket.
2.4. Criar o domínio de saída AVRO
Agora que temos a chave do bucket, copie o valor decimal dela. Continue para criar o output_domain.avro usando a chave do bucket. Substitua
java -jar aggregatable_report_converter.jar \
--request_type createDomainAvro \
--bucket_key <bucket key>
O script cria o arquivo output_domain.avro na pasta atual.
2.5. Criar relatórios de resumo usando a Ferramenta de teste local
Usaremos o LocalTestingTool_{version}.jar que foi baixado na Seção 1.1 para criar os relatórios de resumo. Use o comando a seguir. Substitua LocalTestingTool_{version}.jar pela versão transferida por download para a LocalTestingTool.
Execute o comando a seguir para gerar um relatório de resumo no ambiente de desenvolvimento local:
java -jar LocalTestingTool_{version}.jar \
--input_data_avro_file report.avro \
--domain_avro_file output_domain.avro \
--output_directory .
Você verá algo semelhante à imagem abaixo quando o comando for executado. Um relatório output.avro será criado assim que esse processo for concluído.
2,6 Analisar o relatório de resumo
O relatório de resumo que é criado está no formato AVRO. Para conseguir ler isso, é necessário converter o arquivo do AVRO para o formato JSON. O ideal é que a adtech codifique para converter os relatórios AVRO de volta para JSON.
Para nosso codelab, vamos usar a ferramenta aggregatable_report_converter.jar fornecida para converter o relatório AVRO de volta para JSON.
java -jar aggregatable_report_converter.jar \
--request_type convertToJson \
--input_file output.avro
Um relatório semelhante à imagem a seguir será retornado. Junto com um relatório output.json criado no mesmo diretório.
Abra o arquivo JSON em um editor de sua preferência para analisar o relatório de resumo.
3. Implantação do serviço de agregação
Para implantar o serviço de agregação, siga estas etapas:
Etapa 3: Implantação do serviço de agregação: implante o serviço de agregação na AWS
Etapa 3.1. Clone o repositório de serviços de agregação
Etapa 3.2. Faça o download das dependências pré-criadas
Etapa 3.3. Criar um ambiente de desenvolvimento
Etapa 3.4. Implantar serviço de agregação
3.1. clonar o repositório do serviço de agregação
No seu ambiente local, clone o repositório do GitHub do serviço de agregação.
git clone https://github.com/privacysandbox/aggregation-service.git
3.2. Fazer o download das dependências pré-criadas
Depois de clonar o repositório do serviço de agregação, acesse a pasta do Terraform do repositório e a pasta da nuvem correspondente. Se o cloud_provider for AWS, será possível prosseguir para
cd <repository_root>/terraform/aws
Em download_prebuilt_dependencies.sh.
bash download_prebuilt_dependencies.sh
3.3. Criar um ambiente de desenvolvimento
Crie um ambiente de desenvolvimento em dev.
mkdir dev
Copie o conteúdo da pasta demo para a pasta dev.
cp -R demo/* dev
Mova-o para a pasta dev.
cd dev
Atualize o arquivo main.tf e pressione i em input para editá-lo.
vim main.tf
Retire a marca de comentário do código na caixa vermelha e atualize os nomes do bucket e da chave.
Para main.tf da AWS:
O código sem comentário ficará assim.
backend "s3" {
bucket = "<tf_state_bucket_name>"
key = "<environment_name>.tfstate"
region = "us-east-1"
}
Quando as atualizações estiverem concluídas, salve-as e saia do editor pressionando esc -> :wq!. Isso salva as atualizações de main.tf.
Em seguida, renomeie a example.auto.tfvars como dev.auto.tfvars.
mv example.auto.tfvars dev.auto.tfvars
Atualize o dev.auto.tfvars e pressione i no input para editar o arquivo.
vim dev.auto.tfvars
Atualize os campos na caixa vermelha após a imagem com os parâmetros corretos do ARN da AWS fornecidos durante a integração do serviço de agregação, o ambiente e o e-mail de notificação.
Quando as atualizações forem concluídas, pressione esc -> :wq!. O arquivo dev.auto.tfvars será salvo e ficará parecido com a imagem a seguir.
3.4. Implantar serviço de agregação
Para implantar o serviço de agregação, inicialize o Terraform na mesma pasta
terraform init
Isso retornará algo semelhante a esta imagem:
Depois de inicializar o Terraform, crie o plano de execução. Onde retorna o número de recursos a serem adicionados e outras informações adicionais semelhantes à imagem a seguir.
terraform plan
Confira no resumo "Plano" a seguir. Se esta for uma implantação nova, o número de recursos que serão adicionados vai aparecer, com 0 para alteração e 0 para destruição.
Depois disso, é possível aplicar o Terraform.
terraform apply
Quando a confirmação de execução das ações pelo Terraform for solicitada, insira um yes no valor.
Quando terraform apply for concluído, os seguintes endpoints para createJob e getJob serão retornados. O frontend_api_id que você precisa atualizar no Postman na seção 1.9 também é retornado.
4. Criação de entrada do serviço de agregação
Prossiga com a criação dos relatórios do AVRO para lotes no serviço de agregação.
Etapa 4: Criação de entrada do serviço de agregação: crie os relatórios do serviço de agregação em lote para o serviço de agregação.
Etapa 4.1. Relatório do acionador
Etapa 4.2. Coletar relatórios agregáveis
Etapa 4.3. Converter relatórios para o AVRO
Etapa 4.4. Criar o domínio de saída AVRO
4.1. Acionar relatório
Acesse o site de demonstração do Sandbox de privacidade. Isso aciona um relatório de agregação particular. Confira o relatório em chrome://private-aggregation-internals.
Caso seu relatório tenha o status Pendente, selecione-o e clique em Enviar relatórios selecionados.
4.2. Coletar relatórios agregáveis
Colete os relatórios agregáveis dos endpoints .well-known da API correspondente.
- Agregação particular
[reporting-origin] /.well-known/private-aggregation/report-shared-storage - Relatórios de atribuição: relatório de resumo
[reporting-origin] /.well-known/attribution-reporting/report-aggregate-attribution
Neste codelab, você vai coletar os relatórios manualmente. Na produção, as adtechs precisam coletar e converter os relatórios de forma programática.
Em chrome://private-aggregation-internals, copie o "Corpo do relatório" recebido no endpoint [reporting-origin]/.well-known/private-aggregation/report-shared-storage.
Verifique se em "Corpo do relatório" o aggregation_coordinator_origin contém https://publickeyservice.msmt.aws.privacysandboxservices.com, o que significa que é um relatório agregável da AWS.
Coloque o "Corpo do relatório" JSON em um arquivo JSON. Neste exemplo, você pode usar o vim. Mas você pode usar o editor de texto que quiser.
vim report.json
Cole o relatório em report.json e salve o arquivo.
4.3. Converter relatórios para AVRO
Os relatórios recebidos dos endpoints .well-known estão no formato JSON e precisam ser convertidos para o formato de relatório AVRO. Depois de gerar o relatório JSON, navegue até a pasta de relatórios e use aggregatable_report_converter.jar para criar o relatório agregável de depuração. Isso cria um relatório agregável chamado report.avro no diretório atual.
java -jar aggregatable_report_converter.jar \
--request_type convertToAvro \
--input_file report.json
4.4. Criar o domínio de saída AVRO
Para criar o arquivo output_domain.avro, você precisa das chaves de bucket que podem ser recuperadas dos relatórios.
As chaves de bucket são projetadas pela adtech. No entanto, nesse caso, a demonstração do Sandbox de privacidade do site cria as chaves do bucket. Como a agregação particular desse site está no modo de depuração, é possível usar o debug_cleartext_payload do Corpo do relatório para conseguir a chave do bucket.
Copie o debug_cleartext_payload do corpo do relatório.
Abra goo.gle/ags-payload-decoder e cole o debug_cleartext_payload na caixa INPUT e clique em INPUT.
A página retorna o valor decimal da chave do bucket. Confira a seguir um exemplo de chave de bucket.
Agora que temos a chave do bucket, crie o output_domain.avro. Substitua
java -jar aggregatable_report_converter.jar \
--request_type createDomainAvro \
--bucket_key <bucket key>
O script cria o arquivo output_domain.avro na pasta atual.
4.5. Mover relatórios para o bucket da AWS
Depois que os relatórios AVRO (da seção 3.2.3) e o domínio de saída (da seção 3.2.4) forem criados, mova os relatórios e o domínio de saída para os buckets de relatórios do S3.
Se você tiver a CLI da AWS configurada no ambiente local, use os comandos a seguir para copiar os relatórios para o bucket do S3 e a pasta de relatórios correspondentes.
aws s3 cp report.avro s3://<report_bucket_name>/<report_folder>/
aws s3 cp output_domain.avro s3://<report_bucket_name>/<output_domain_folder>/
5. Uso do serviço de agregação
No terraform apply, são retornados create_job_endpoint, get_job_endpoint e frontend_api_id. Copie o frontend_api_id e coloque-o na variável global frontend_api_id do postman que você configurou na seção 1.9 de pré-requisitos.
Etapa 5: Uso do serviço de agregação: use a API Aggregate Service para criar e analisar relatórios resumidos.
Etapa 5.1. Usar o endpoint createJob para agrupar em lotes
Etapa 5.2. Usar o endpoint getJob para recuperar o status do lote
Etapa 5.3. Revisão do relatório de resumo
5.1. Usando o endpoint createJob para lotes
No Postman, abra a coleção "Sandbox de privacidade" e selecione "createJob".
Selecione "Body" e "raw" para inserir o payload da sua solicitação.
O esquema de payload createJob está disponível no github e é semelhante ao seguinte. Substitua <> pelos campos apropriados.
{
"job_request_id": "<job_request_id>",
"input_data_blob_prefix": "<report_folder>/<report_name>.avro",
"input_data_bucket_name": "<input_bucket_name>",
"output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
"output_data_bucket_name": "<output_bucket_name>",
"job_parameters": {
"output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
"output_domain_bucket_name": "<output_domain_bucket_name>",
"attribution_report_to": "<reporting origin of report>",
"report_error_threshold_percentage": "10",
"debug_run": "true"
}
}
Depois de clicar em Send, o job será criado com job_request_id. Você vai receber uma resposta HTTP 202 quando a solicitação for aceita pelo serviço de agregação. Outro código de retorno possível pode ser encontrado em códigos de resposta HTTP
5.2. Como usar o endpoint getJob para recuperar o status do lote
Para verificar o status da solicitação do job, use o endpoint getJob. Selecione "getJob" na coleção "Sandbox de privacidade".
Em "Params", atualize o valor job_request_id para o job_request_id enviado na solicitação createJob.
O resultado de getJob retornará o status da solicitação de job com um status HTTP 200. A solicitação "Body" contém as informações necessárias, como job_status, return_message e error_messages (se o job tiver gerado um erro).
Como o site de relatórios do relatório de demonstração gerado é diferente do site integrado no ID da AWS, você pode receber uma resposta com PRIVACY_BUDGET_AUTHORIZATION_ERROR return_code. Isso é normal, já que o site da origem de relatórios dos relatórios não corresponde ao site integrado ao ID da AWS.
{
"job_status": "FINISHED",
"request_received_at": "2023-12-07T22:50:58.830956Z",
"request_updated_at": "2023-12-07T22:51:10.526326456Z",
"job_request_id": "<job_request_id>",
"input_data_blob_prefix": "<report_folder>/<report_name>.avro",
"input_data_bucket_name": "<input_bucket_name>",
"output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
"output_data_bucket_name": "<output_bucket_name>",
"postback_url": "",
"result_info": {
"return_code": "PRIVACY_BUDGET_AUTHORIZATION_ERROR",
"return_message": "Aggregation job successfully processed",
"error_summary": {
"error_counts": [],
"error_messages": []
},
"finished_at": "2023-12-07T22:51:10.517730898Z"
},
"job_parameters": {
"debug_run": "true",
"output_domain_bucket_name": "<output_domain_bucket_name>",
"output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
"attribution_report_to": "https://privacy-sandbox-demos-dsp.dev"
},
"request_processing_started_at": "2023-12-07T22:51:06.034472697Z"
}
5.3. Revisão do relatório de resumo
Depois de receber o relatório de resumo no bucket de saída do S3, faça o download dele para o ambiente local. Os relatórios de resumo estão no formato AVRO e podem ser convertidos de volta para um JSON. Você pode usar aggregatable_report_converter.jar para ler o relatório usando o comando a seguir.
java -jar aggregatable_report_converter.jar \
--request_type convertToJson \
--input_file <summary_report_avro>
Isso retorna um JSON de valores agregados de cada chave de bucket que é semelhante à imagem a seguir.
Se a solicitação createJob incluir debug_run como true, você poderá receber o relatório de resumo na pasta de depuração, localizada em output_data_blob_prefix. O relatório está no formato AVRO e pode ser convertido usando o comando anterior para um JSON.
O relatório contém a chave do bucket, a métrica sem ruído e o ruído que é adicionado à métrica sem ruído para formar o relatório de resumo. O relatório é semelhante à imagem abaixo.
As anotações também contêm in_reports e in_domain, o que significa que:
- in_reports: a chave do bucket está disponível nos relatórios agregáveis.
- in_domain - a chave do bucket está disponível dentro do arquivo AVRO output_domain.