1. Prerequisiti
Per eseguire questo codelab, sono richiesti alcuni prerequisiti. Ogni requisito viene contrassegnato di conseguenza, se è obbligatorio per "Test locale" o "Servizio di aggregazione".
1.1. Scarica lo strumento di test locale (Local Testing Tool)
I test locali richiedono il download dello strumento. Lo strumento genera report di riepilogo dai report di debug non criptati.
Lo strumento di test locale è disponibile per il download in Lambda JAR Archives in GitHub. Deve essere denominato LocalTestingTool_{version}.jar.
1.2. Assicurati che JAVA JRE sia installato (servizio locale di test e aggregazione)
Apri "Terminale" e usa java --version per verificare se sulla tua macchina è installato Java o openJDK.
Se non è installata, puoi scaricarla e installarla dal sito Java o dal sito openJDK.
1.3. Scarica il convertitore di report aggregati (servizio di aggregazione e test locali)
Puoi scaricare una copia del convertitore di report aggregabili dal repository GitHub di Privacy Sandbox Demos.
1.4 Abilita le API Privacy Sandbox (servizio di aggregazione e test locali)
Sul browser, vai a chrome://flags/#privacy-sandbox-ads-apis e attiva le API Privacy Sandbox.
Assicurati che i cookie di terze parti siano abilitati.
Sul browser, vai all'indirizzo chrome://settings/cookies e seleziona "Blocca cookie di terze parti in modalità di navigazione in incognito".
1.5. Registrazione web e Android (Aggregation Service)
Per utilizzare le API Privacy Sandbox in un ambiente di produzione, assicurati di aver completato la registrazione e l'attestazione per Chrome e Android.
Per i test locali, la registrazione può essere disattivata utilizzando un flag di Chrome e un'opzione dell'interfaccia a riga di comando.
Per utilizzare il flag di Chrome per la nostra demo, vai a chrome://flags/#privacy-sandbox-enrollment-overrides e aggiorna l'override con il tuo sito oppure, se userai il nostro sito dimostrativo, non è necessario alcun aggiornamento.
1.6. Onboarding di Aggregation Service (Aggregation Service)
Il servizio di aggregazione richiede l'inserimento dei coordinatori per poter utilizzare il servizio. Compila il modulo di onboarding di Aggregation Service fornendo l'indirizzo del sito dei report, l'ID account AWS e altre informazioni.
1.7 Cloud provider (Aggregation Service)
Aggregation Service richiede l'uso di un ambiente di esecuzione affidabile, che prevede l'uso di un ambiente cloud. Il servizio di aggregazione è supportato su Amazon Web Services (AWS) e Google Cloud (GCP). Questo codelab riguarderà solo l'integrazione AWS.
AWS offre un ambiente di esecuzione affidabile chiamato Nitro Enclaves. Assicurati di avere un account AWS e segui le istruzioni di installazione e aggiornamento di AWS CLI per configurare l'ambiente AWS CLI.
Se AWS CLI è nuovo, puoi configurarla seguendo le istruzioni per la configurazione dell'interfaccia a riga di comando.
1.7.1. Crea bucket AWS S3
Crea un bucket AWS S3 per archiviare lo stato di Terraform e un altro bucket S3 per archiviare i report e i report di riepilogo. Puoi utilizzare il comando dell'interfaccia a riga di comando fornito. Sostituisci il campo in <> con le variabili appropriate.
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. Crea chiave di accesso utente
Crea le chiavi di accesso degli utenti utilizzando la guida di AWS. Verrà utilizzato per chiamare gli endpoint API createJob e getJob creati su AWS.
1.7.3. Autorizzazioni utente e gruppo AWS
Per eseguire il deployment di Aggregation Service su AWS, devi fornire determinate autorizzazioni all'utente utilizzato per il deployment del servizio. Per questo codelab, assicurati che l'utente disponga dell'accesso come amministratore, in modo da assicurare autorizzazioni complete durante il deployment.
1.8 Terraform (servizio di aggregazione)
Questo codelab utilizza Terraform per il deployment del servizio di aggregazione. Assicurati che il binario Terraform sia installato nel tuo ambiente locale.
Scarica il binario Terraform nel tuo ambiente locale.
Una volta scaricato il programma binario Terraform, estrai il file e spostalo in /usr/local/bin.
cp <directory>/terraform /usr/local/bin
Verifica che Terraform sia disponibile su classpath.
terraform -v
1.9 Postman (per Aggregation Service AWS)
Per questo codelab, utilizza Postman per la gestione delle richieste.
Per creare un'area di lavoro, vai all'elemento di navigazione in alto "Aree di lavoro" e seleziona "Crea area di lavoro".
Seleziona "Area di lavoro vuota", fai clic su Avanti e assegnale il nome "Privacy Sandbox". Seleziona "Personale" e fai clic su "Crea".
Scarica i file Configurazione JSON e Ambiente globale dell'area di lavoro preconfigurati.
Importa i file JSON in "La mia area di lavoro" utilizzando il pulsante "Importa".
Verrà creata la raccolta Privacy Sandbox per te insieme alle richieste HTTP createJob e getJob.
Aggiorna "Access Key" e "Secret Key" di AWS tramite "Ricerca rapida dell'ambiente".
Fai clic su "Modifica" e aggiorna il "Valore attuale" sia di "access_key" che di "secret_key". Tieni presente che frontend_api_id sarà fornito nella sezione 3.1.4 del presente documento. Consigliamo di utilizzare la regione us-east-1. Tuttavia, se vuoi eseguire il deployment in un'altra regione, assicurati di copiare l'AMI rilasciata nel tuo account o di eseguire una creazione autonoma utilizzando gli script forniti.
2. Codelab per i test locali
Puoi utilizzare lo strumento di test locale sul tuo computer per eseguire l'aggregazione e generare report di riepilogo utilizzando i report di debug non criptati.
Passaggi del codelab
Passaggio 2.1. Attiva report: attiva i report di aggregazione privata per poter raccogliere il report.
Passaggio 2.2. Crea un report aggregabile di debug: converti il report JSON raccolto in un report in formato AVRO.
Questo passaggio sarà simile a quello in cui i tecnici pubblicitari raccolgono i report dagli endpoint di reporting dell'API e convertiranno i report JSON in report in formato AVRO.
Passaggio 2.3. Analizza la chiave del bucket dal report di debug: le chiavi dei bucket sono progettate da tecnici pubblicitari. Poiché i bucket sono predefiniti, in questo codelab recupera le chiavi dei bucket come indicato.
Passaggio 2.4. Crea l'AVRO del dominio di output: dopo aver recuperato le chiavi del bucket, crea il file AVRO del dominio di output.
Passaggio 2.5. Crea report di riepilogo con lo strumento di test locale: utilizza questo strumento di test locale per creare report di riepilogo nell'ambiente locale.
Passaggio 2.6. Esamina il report di riepilogo: esamina il report di riepilogo creato dallo Strumento di test locale.
2.1. Attiva report
Vai al sito della demo di Privacy Sandbox. In questo modo viene attivato un report di aggregazione privato. Puoi visualizzare il report all'indirizzo chrome://private-aggregation-internals.
Se il report è nello stato "In attesa", puoi selezionarlo e fare clic su "Invia report selezionati".
2.2. Crea report aggregabile di debug
In chrome://private-aggregation-internals, copia il "Corpo del report" ricevuto nell'endpoint [reporting-origin]/.well-known/private-aggregation/report-shared-storage.
Assicurati che nel "Corpo del report" l'aggregation_coordinator_origin contenga https://publickeyservice.msmt.aws.privacysandboxservices.com, il che significa che il report è un report aggregabile AWS.
Inserisci il "Corpo del report" JSON in un file JSON. In questo esempio puoi usare vim. Tuttavia, puoi utilizzare l'editor di testo che preferisci.
vim report.json
Incolla il report in report.json e salva il file.
Dopodiché, vai alla cartella del report e utilizza aggregatable_report_converter.jar per creare il report aggregabile di debug. Nella tua directory attuale viene creato un report aggregabile denominato report.avro.
java -jar aggregatable_report_converter.jar \
--request_type convertToAvro \
--input_file report.json \
--debug
2.3. Analizza la chiave del bucket dal report di debug
Aggregation Service richiede due file durante il raggruppamento. Il report aggregabile e il file del dominio di output. Il file del dominio di output contiene le chiavi che vuoi recuperare dai report aggregabili. Per creare il file output_domain.avro, sono necessarie le chiavi dei bucket che possono essere recuperate dai report.
Le chiavi dei bucket vengono progettate dal chiamante dell'API e la demo contiene chiavi di bucket di esempio precostruite. Poiché la demo ha abilitato la modalità di debug per l'aggregazione privata, puoi analizzare il payload in chiaro di debug dal "Corpo del report" per recuperare la chiave del bucket. Tuttavia, in questo caso, la demo di Privacy Sandbox del sito crea le chiavi dei bucket. Poiché l'aggregazione privata per questo sito è in modalità di debug, puoi utilizzare l'elemento debug_cleartext_payload dal "Corpo del report" per ottenere la chiave del bucket.
Copia il debug_cleartext_payload dal corpo del report.
Apri lo strumento Debug payload per Aggregation e incolla debug_cleartext_payload nella casella "INPUT" e fai clic su "Decodifica".
La pagina restituisce il valore decimale della chiave del bucket. Di seguito è riportata una chiave di bucket di esempio.
2.4. Crea l'AVRO del dominio di output
Ora che abbiamo la chiave del bucket, copia il valore decimale della chiave del bucket. Procedi per creare output_domain.avro utilizzando la chiave del bucket. Assicurati di sostituire
java -jar aggregatable_report_converter.jar \
--request_type createDomainAvro \
--bucket_key <bucket key>
Lo script crea il file output_domain.avro nella cartella corrente.
2.5 Crea report di riepilogo utilizzando Local Testing Tool
Utilizzeremo i report LocalTestingTool_{version}.jar scaricati nella Sezione 1.1 per creare i report di riepilogo. Utilizza il seguente comando. Devi sostituire LocalTestingTool_{version}.jar con la versione scaricata per LocalTestingTool.
Esegui questo comando per generare un report di riepilogo nel tuo ambiente di sviluppo locale:
java -jar LocalTestingTool_{version}.jar \
--input_data_avro_file report.avro \
--domain_avro_file output_domain.avro \
--output_directory .
Una volta eseguito il comando, dovresti vedere qualcosa di simile alla seguente immagine. Al termine, verrà creato un report output.avro.
2.6 Esamina il report di riepilogo
Il report di riepilogo creato è in formato AVRO. Per poterlo leggere, devi convertirlo da AVRO in un formato JSON. Idealmente, l'ad tech dovrebbe programmare per convertire i report AVRO in JSON.
Per il nostro codelab, utilizzeremo lo strumento aggregatable_report_converter.jar fornito per convertire il report AVRO in formato JSON.
java -jar aggregatable_report_converter.jar \
--request_type convertToJson \
--input_file output.avro
Verrà restituito un report simile alla seguente immagine. È inoltre presente un report output.json creato nella stessa directory.
Apri il file JSON in un editor a tua scelta per esaminare il report di riepilogo.
3. Deployment di Aggregation Service
Per eseguire il deployment di Aggregation Service, segui questi passaggi:
Passaggio 3: Deployment di Aggregation Service: esegui il deployment di Aggregation Service su AWS
Passaggio 3.1. Clona il repository di servizi di aggregazione
Passaggio 3.2. Scarica le dipendenze predefinite
Passaggio 3.3. Crea un ambiente di sviluppo
Passaggio 3.4. Esegui il deployment del servizio di aggregazione
3.1. clona il repository di Aggregation Service
Nel tuo ambiente locale, clona il repository GitHub di Aggregation Service.
git clone https://github.com/privacysandbox/aggregation-service.git
3.2. Scarica le dipendenze predefinite
Dopo aver clonato il repository di Aggregation Service, vai alla cartella Terraform del repository e alla cartella cloud corrispondente. Se il tuo cloud_provider è AWS, puoi procedere con
cd <repository_root>/terraform/aws
In download_prebuilt_dependencies.sh.
bash download_prebuilt_dependencies.sh
3.3 Crea un ambiente di sviluppo
Crea un ambiente di sviluppo in dev.
mkdir dev
Copia i contenuti della cartella demo nella cartella dev.
cp -R demo/* dev
Sposta nella tua cartella dev.
cd dev
Aggiorna il file main.tf e premi i per input per modificarlo.
vim main.tf
Rimuovi il commento dal codice nella casella rossa rimuovendo il simbolo # e aggiornando i nomi dei bucket e delle chiavi.
Per AWS main.tf:
Il codice non commentato dovrebbe essere simile al seguente.
backend "s3" {
bucket = "<tf_state_bucket_name>"
key = "<environment_name>.tfstate"
region = "us-east-1"
}
Una volta portati a termine gli aggiornamenti, salvali e esci dall'editor premendo esc -> :wq!. Gli aggiornamenti verranno salvati il giorno main.tf.
Quindi, rinomina example.auto.tfvars in dev.auto.tfvars.
mv example.auto.tfvars dev.auto.tfvars
Aggiorna dev.auto.tfvars e premi i per input per modificare il file.
vim dev.auto.tfvars
Aggiorna i campi nella casella rossa seguente l'immagine con i parametri AWS ARN corretti che vengono forniti durante l'onboarding, l'ambiente e l'email di notifica di Aggregation Service.
Una volta completati gli aggiornamenti, premi esc -> :wq!. Il file dev.auto.tfvars viene salvato e dovrebbe avere un aspetto simile all'immagine seguente.
3.4. Esegui il deployment del servizio di aggregazione
Per eseguire il deployment di Aggregation Service, inizializza Terraform nella stessa cartella
terraform init
Dovrebbe essere restituito qualcosa di simile alla seguente immagine:
Dopo aver inizializzato Terraform, crea il piano di esecuzione Terraform. dove restituisce il numero di risorse da aggiungere e altre informazioni aggiuntive simili all'immagine seguente.
terraform plan
Puoi vedere quanto segue nel riepilogo "Piano". Se si tratta di un nuovo deployment, dovresti vedere il numero di risorse che verranno aggiunte: 0 da modificare e 0 da eliminare.
Una volta completato questo passaggio, puoi procedere con l'applicazione di Terraform.
terraform apply
Quando Terraform ti chiede di confermare l'esecuzione delle azioni, inserisci yes nel valore.
Al termine di terraform apply, vengono restituiti i seguenti endpoint per createJob e getJob. Viene restituito anche il valore frontend_api_id che devi aggiornare in Postman nella sezione 1.9.
4. Creazione dell'input del servizio di aggregazione
Procedi alla creazione dei report AVRO per il raggruppamento in batch nel servizio di aggregazione.
Passaggio 4: Creazione dell'input del servizio di aggregazione: crea i report di Aggregation Service raggruppati per il servizio di aggregazione.
Passaggio 4.1. Report sul trigger
Passaggio 4.2. Raccogliere report aggregabili
Passaggio 4.3. Converti i report in AVRO
Passaggio 4.4. Crea l'AVRO del dominio di output
4.1. Attiva report
Vai al sito della demo di Privacy Sandbox. In questo modo viene attivato un report di aggregazione privato. Puoi visualizzare il report all'indirizzo chrome://private-aggregation-internals.
Se il report è nello stato "In attesa", puoi selezionarlo e fare clic su "Invia report selezionati".
4.2. Raccogliere report aggregabili
Raccogli i report aggregabili dagli endpoint .well-known dell'API corrispondente.
- Aggregazione privata
[reporting-origin] /.well-known/private-aggregation/report-shared-storage - Reporting sull'attribuzione - Report di riepilogo
[reporting-origin] /.well-known/attribution-reporting/report-aggregate-attribution
Per questo codelab, eseguirai la raccolta manuale dei report. In produzione, i tecnici pubblicitari sono tenuti a raccogliere e convertire i report in modo programmatico.
In chrome://private-aggregation-internals, copia il "Corpo del report" ricevuto nell'endpoint [reporting-origin]/.well-known/private-aggregation/report-shared-storage.
Assicurati che nel "Corpo del report" l'aggregation_coordinator_origin contenga https://publickeyservice.msmt.aws.privacysandboxservices.com, il che significa che il report è un report aggregabile AWS.
Inserisci il "Corpo del report" JSON in un file JSON. In questo esempio puoi usare vim. Tuttavia, puoi utilizzare l'editor di testo che preferisci.
vim report.json
Incolla il report in report.json e salva il file.
4.3. Converti i report in AVRO
I report ricevuti dagli endpoint .well-known sono in formato JSON e devono essere convertiti nel formato di report AVRO. Una volta ottenuto il report JSON, vai alla cartella del report e utilizza aggregatable_report_converter.jar per creare il report aggregabile di debug. Nella tua directory attuale viene creato un report aggregabile denominato report.avro.
java -jar aggregatable_report_converter.jar \
--request_type convertToAvro \
--input_file report.json
4.4. Crea l'AVRO del dominio di output
Per creare il file output_domain.avro, sono necessarie le chiavi dei bucket che possono essere recuperate dai report.
Le chiavi dei bucket sono progettate dalla tecnologia pubblicitaria, ma in questo caso la demo di Privacy Sandbox del sito crea le chiavi dei bucket. Poiché l'aggregazione privata per questo sito è in modalità di debug, puoi utilizzare l'elemento debug_cleartext_payload dal "Corpo del report" per ottenere la chiave del bucket.
Procedi e copia il debug_cleartext_payload dal corpo del report.
Apri goo.gle/ags-payload-decoder e incolla il tuo debug_cleartext_payload nella casella "INPUT" e fai clic su "Decodifica".
La pagina restituisce il valore decimale della chiave del bucket. Di seguito è riportata una chiave di bucket di esempio.
Ora che abbiamo la chiave del bucket, crea il output_domain.avro. Assicurati di sostituire
java -jar aggregatable_report_converter.jar \
--request_type createDomainAvro \
--bucket_key <bucket key>
Lo script crea il file output_domain.avro nella cartella corrente.
4.5. Sposta i report nel bucket AWS
Una volta creati i report AVRO (dalla sezione 3.2.3) e il dominio di output (dalla sezione 3.2.4), procedere con lo spostamento dei report e del dominio di output nei bucket S3 di reporting.
Se hai configurato AWS CLI sul tuo ambiente locale, utilizza i comandi seguenti per copiare i report nel bucket S3 e nella cartella dei report corrispondenti.
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. Utilizzo del servizio di aggregazione
Da terraform apply, ti verranno restituiti i create_job_endpoint, i get_job_endpoint e i frontend_api_id. Copia il valore frontend_api_id e inseriscilo nella variabile globale Postman frontend_api_id che hai configurato nella sezione dei prerequisiti 1.9.
Passaggio 5: Aggregation Service Usage: utilizza l'API Aggregation Service per creare report di riepilogo ed esaminarli.
Passaggio 5.1. Utilizzo dell'endpoint createJob per l'esecuzione in batch
Passaggio 5.2. Utilizzo dell'endpoint getJob per recuperare lo stato del batch
Passaggio 5.3. Esaminare il report di riepilogo
5.1. Utilizzo dell'endpoint createJob per il batch
In Postman, apri la raccolta "Privacy Sandbox" e seleziona "createJob".
Seleziona "Corpo" e poi "raw" per inserire il payload della richiesta.
Lo schema del payload createJob è disponibile in github ed è simile al seguente. Sostituisci <> con i campi appropriati.
{
"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"
}
}
Dopo aver fatto clic su "Invia", viene creato il job con job_request_id. Dovresti ricevere una risposta HTTP 202 una volta che la richiesta è stata accettata dal servizio di aggregazione. Un altro possibile codice restituito è disponibile nella pagina Codici di risposta HTTP
5.2. utilizzo dell'endpoint getJob per recuperare lo stato batch
Per controllare lo stato della richiesta del job, puoi utilizzare l'endpoint getJob. Seleziona "getJob" nella raccolta "Privacy Sandbox".
In "Params", aggiorna il valore job_request_id impostandolo sul valore job_request_id inviato nella richiesta createJob.
Il risultato dell'istruzione getJob dovrebbe restituire lo stato della richiesta del job con uno stato HTTP di 200. La richiesta "Corpo" contiene le informazioni necessarie, ad esempio job_status, return_message e error_messages (se il job ha generato errori).
Poiché il sito di reporting del report demo generato è diverso dal sito di onboarding nell'ID AWS, potresti ricevere una risposta con PRIVACY_BUDGET_AUTHORIZATION_ERRORreturn_code. Questo è normale poiché il sito di origine dei report dei report non corrisponde al sito del report registrato per l'ID 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-news.dev"
},
"request_processing_started_at": "2023-12-07T22:51:06.034472697Z"
}
5.3. Esaminare il report di riepilogo
Una volta ricevuto il report di riepilogo nel bucket S3 di output, puoi scaricarlo nel tuo ambiente locale. I report di riepilogo sono in formato AVRO e possono essere riconvertiti in JSON. Puoi utilizzare aggregatable_report_converter.jar per leggere il report con il seguente comando.
java -jar aggregatable_report_converter.jar \
--request_type convertToJson \
--input_file <summary_report_avro>
Questo restituisce un JSON dei valori aggregati di ogni chiave del bucket simile alla seguente immagine.
Se la tua richiesta createJob include debug_run come true, puoi ricevere il report di riepilogo nella cartella di debug che si trova all'interno di output_data_blob_prefix. Il report è in formato AVRO e può essere convertito in formato JSON utilizzando il comando precedente.
Il report contiene la chiave del bucket, la metrica senza rumore e il rumore che viene aggiunto a quest'ultima per formare il report di riepilogo. Il report è simile all'immagine seguente.
Le annotazioni contengono anche in_reports e in_domain, il che significa che:
- in_reports: la chiave del bucket è disponibile all'interno dei report aggregabili.
- in_domain: la chiave del bucket è disponibile all'interno del file AVRO output_domain.