1. Prerequisiti
Per eseguire questo codelab, sono richiesti alcuni prerequisiti. Ogni requisito viene contrassegnato come richiesto per i "Test locali". o "Servizio di aggregazione".
1.1. Scarica lo strumento di test locale (test locale)
Per i test locali sarà necessario scaricare lo strumento di test locale. Lo strumento genererà report di riepilogo dai report di debug non criptati.
Lo strumento di test locale è disponibile per il download da Lambda JAR Archives in GitHub. Dovrebbe essere denominato LocalTestingTool_{version}.jar.
1.2. Assicurati che JAVA JRE sia installato (servizio di test e aggregazione locale)
Apri "Terminale" e usa java --version per verificare se sulla macchina è installato Java o openJDK.
Se non è installato, puoi scaricarlo e installarlo dal sito Java o dal sito di openJDK.
1.3. Scarica il convertitore di report aggregati (servizio di test e aggregazione locale)
Puoi scaricare una copia del convertitore di report aggregabili dal repository GitHub di Privacy Sandbox Demos.
1.4. Attiva le API di privacy per gli annunci (servizio di test e aggregazione locale)
Nel browser, vai a chrome://settings/adPrivacy e attiva tutte le API di privacy per gli annunci.
Assicurati che i cookie di terze parti siano abilitati.
Sul browser, vai a chrome://settings/cookies e seleziona "Blocca i cookie di terze parti in modalità di navigazione in incognito".
1.5. Registrazione web e Android (servizio di aggregazione)
Per utilizzare le API Privacy Sandbox in un ambiente di produzione, assicurati di aver completato la registrazione e l'attestazione sia per Chrome sia per 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. In alternativa, se utilizzerai il nostro sito demo, non è necessario alcun aggiornamento.
1.6. Onboarding del servizio di aggregazione (servizio di aggregazione)
Il servizio di aggregazione richiede l'onboarding dei coordinatori per poterlo utilizzare. Compila il modulo di onboarding del servizio di aggregazione fornendo l'indirizzo del sito di reporting, l'ID account AWS e altre informazioni.
1.7. Cloud provider (servizio di aggregazione)
Il servizio di aggregazione richiede l'uso di un ambiente di esecuzione affidabile che utilizza un ambiente cloud. Il servizio di aggregazione è supportato su Amazon Web Services (AWS) e Google Cloud (Google Cloud). Questo codelab riguarda solo l'integrazione con AWS.
AWS fornisce un ambiente di esecuzione affidabile chiamato Nitro Enclaves. Assicurati di avere un account AWS e segui le istruzioni per l'installazione e l'aggiornamento dell'interfaccia a riga di comando di AWS per configurare l'ambiente AWS CLI.
Se l'interfaccia a riga di comando AWS è nuova, puoi configurarla utilizzando le istruzioni di configurazione dell'interfaccia a riga di comando.
1.7.1. Crea un 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 del servizio di aggregazione su AWS, devi fornire determinate autorizzazioni all'utente utilizzato per il deployment del servizio. Per questo codelab, assicurati che l'utente disponga dell'accesso amministrativo per garantire autorizzazioni complete nel deployment.
1.8. Terraform (servizio di aggregazione)
Questo codelab utilizza Terraform per eseguire il deployment del servizio di aggregazione. Assicurati che il programma binario Terraform sia installato nell'ambiente locale.
Scarica il file 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 il servizio di aggregazione AWS)
Per questo codelab, utilizza Postman per la gestione delle richieste.
Per creare un'area di lavoro, vai a "Aree di lavoro" l'elemento di navigazione in alto 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 preconfigurati della configurazione JSON e dell'ambiente globale dell'area di lavoro.
Importa i file JSON in "Il mio spazio di lavoro" utilizzando il pulsante "Importa" .
Verrà creata la raccolta Privacy Sandbox per te insieme alle richieste HTTP createJob e getJob.
Aggiorna la "chiave di accesso" di AWS e "Secret Key" (Chiave segreta) tramite "Panoramica rapida dell'ambiente".
Fai clic su "Modifica". e aggiornare il "Valore attuale" di "access_key" e "secret_key". Tieni presente che il campo frontend_api_id verrà fornito nella sezione 3.1.4 di questo documento. Ti consigliamo inoltre di utilizzare la regione us-east-1. Tuttavia, se vuoi eseguire il deployment in una regione diversa, assicurati di copiare l'AMI rilasciata nel tuo account o di eseguire una build autonoma utilizzando gli script forniti.
2. Codelab sui 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 sull'aggregazione privata per poter raccogliere il report.
Passaggio 2.2. Creare un report aggregabile di debug: converti il report JSON raccolto in un report in formato AVRO.
Questo passaggio sarà simile a quando i tecnici pubblicitari raccolgono i report dagli endpoint di reporting dell'API e convertono 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 dai tecnici pubblicitari. In questo codelab, poiché i bucket sono predefiniti, recupera le chiavi dei bucket come previsto.
Passaggio 2.4. Crea il file AVRO del dominio di output: una volta recuperate le chiavi dei bucket, crea il file AVRO del dominio di output.
Passaggio 2.5. Crea report di riepilogo utilizzando lo strumento di test locale: utilizza lo strumento di test locale per poter creare report di riepilogo nell'ambiente locale.
Passaggio 2.6. Esamina il rapporto di riepilogo: esamina il rapporto di riepilogo creato dallo strumento di test locale.
2.1. Attiva report
Visita il sito 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 selezionare il report e fare clic su "Invia report selezionati".
2.2. Creare un 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" il aggregation_coordinator_origin contenga https://publickeyservice.msmt.aws.privacysandboxservices.com, il che significa che il report è un report di AWS aggregabile.
Inserisci il "Corpo del report" JSON in un file JSON. In questo esempio, puoi utilizzare vim. ma puoi utilizzare qualsiasi editor di testo.
vim report.json
Incolla il report in report.json e salva il file.
Una volta trovato, vai alla cartella del report e usa aggregatable_report_converter.jar per creare il report aggregabile di debug. In questo modo, nella directory attuale viene creato un report aggregabile chiamato 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
Il servizio di aggregazione richiede due file durante il batch. 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, hai bisogno delle chiavi dei bucket che è possibile recuperare dai report.
Le chiavi dei bucket sono progettate dal chiamante dell'API e la demo contiene chiavi di bucket di esempio preconfigurate. Poiché la demo ha abilitato la modalità di debug per l'aggregazione privata, puoi analizzare il payload di testo 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 valore debug_cleartext_payload dal corpo del report.
Apri lo strumento Debug payload decoder for Private Aggregation e incolla il debug_cleartext_payloadnel "INPUT" e fai clic su "Decodifica".
La pagina restituisce il valore decimale della chiave del bucket. Di seguito è riportato un esempio di chiave di bucket.
2.4. Crea il dominio di output AVRO
Ora che abbiamo la chiave del bucket, copia il valore decimale della chiave. Procedi alla creazione dell'oggetto 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. Creare report di riepilogo utilizzando lo strumento di test locale
Utilizzeremo l'elemento LocalTestingTool_{version}.jar scaricato 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, il risultato dovrebbe essere simile all'immagine seguente. Al termine dell'operazione, verrà creato un report output.avro.
2.6. Esaminare il report di riepilogo
Il report di riepilogo creato è in formato AVRO. Per poterlo leggere, devi convertirlo da AVRO a un formato JSON. Idealmente, la tecnologia pubblicitaria dovrebbe programmare per riconvertire i report AVRO in JSON.
Per il nostro codelab, utilizzeremo lo strumento aggregatable_report_converter.jar fornito per riconvertire il report AVRO in JSON.
java -jar aggregatable_report_converter.jar \
--request_type convertToJson \
--input_file output.avro
Viene restituito un report simile all'immagine seguente. È inoltre presente un report output.json creato nella stessa directory.
Apri il file JSON in un editor di tua scelta per esaminare il report di riepilogo.
3. Deployment del servizio di aggregazione
Per eseguire il deployment del servizio di aggregazione, segui questi passaggi:
Passaggio 3. Deployment del servizio di aggregazione: esegui il deployment del servizio di aggregazione su AWS
Passaggio 3.1. Clona il repository dei 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 del servizio di aggregazione
Nel tuo ambiente locale, clona il repository GitHub del servizio di aggregazione.
git clone https://github.com/privacysandbox/aggregation-service.git
3.2. Scarica dipendenze predefinite
Una volta clonato il repository del servizio di aggregazione, 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 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 del bucket e della chiave.
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 ed esci dall'editor premendo esc -> :wq!. Gli aggiornamenti verranno salvati su main.tf.
Successivamente, 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 con i parametri AWS ARN corretti forniti durante l'onboarding, l'ambiente e l'email di notifica del servizio di aggregazione.
Una volta terminati gli aggiornamenti, premi esc -> :wq!. Il file dev.auto.tfvars verrà salvato, e dovrebbe avere un aspetto simile all'immagine seguente.
3.4. Esegui il deployment del servizio di aggregazione
Per eseguire il deployment del servizio di aggregazione, nella stessa cartella
terraform init
L'immagine dovrebbe essere simile alla seguente:
Una volta 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: "Piano" riassunto. Se si tratta di un deployment nuovo, dovresti vedere il numero di risorse che verranno aggiunte, con 0 per la modifica e 0 per l'eliminazione.
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 un yes nel valore.
Al termine di terraform apply, vengono restituiti i seguenti endpoint per createJob e getJob. Viene restituito anche il frontend_api_id che devi aggiornare in Postman nella sezione 1.9.
4. Creazione di input del servizio di aggregazione
Procedi alla creazione dei report AVRO per il raggruppamento in batch nel servizio di aggregazione.
Passaggio 4. Creazione di input del servizio di aggregazione: crea i report del servizio di aggregazione che vengono raggruppati in batch per il servizio di aggregazione.
Passaggio 4.1. Report attivatore
Passaggio 4.2. Raccogliere report aggregabili
Passaggio 4.3. Converti i report in AVRO
Passaggio 4.4. Crea il dominio di output AVRO
4.1. Attiva report
Vai al sito 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 selezionare il report 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 - Attribution Reporting - Report di riepilogo
[reporting-origin] /.well-known/attribution-reporting/report-aggregate-attribution
Per questo codelab, effettuerai la raccolta manuale dei report. In fase di produzione, i tecnici pubblicitari dovrebbero 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" il aggregation_coordinator_origin contenga https://publickeyservice.msmt.aws.privacysandboxservices.com, il che significa che il report è un report di AWS aggregabile.
Inserisci il "Corpo del report" JSON in un file JSON. In questo esempio, puoi utilizzare vim. ma puoi utilizzare qualsiasi editor di testo.
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 in formato di report AVRO. Una volta ottenuto il report JSON, vai alla cartella del report e usa aggregatable_report_converter.jar per creare il report aggregabile di debug. In questo modo, nella directory attuale viene creato un report aggregabile chiamato report.avro.
java -jar aggregatable_report_converter.jar \
--request_type convertToAvro \
--input_file report.json
4.4. Crea il dominio di output AVRO
Per creare il file output_domain.avro, hai bisogno delle chiavi dei bucket che è possibile recuperare dai report.
Le chiavi dei bucket sono progettate dalla tecnologia pubblicitaria. 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 goo.gle/ags-payload-decoder e incolla il tuo debug_cleartext_payload in "INPUT" e fai clic su "Decodifica".
La pagina restituisce il valore decimale della chiave del bucket. Di seguito è riportato un esempio di chiave di bucket.
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 nel tuo ambiente locale, utilizza i seguenti comandi 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 create_job_endpoint, get_job_endpoint e frontend_api_id. Copia il frontend_api_id e inseriscilo nella variabile globale postman frontend_api_id che hai configurato nella sezione dei prerequisiti 1.9.
Passaggio 5. Utilizzo del servizio di aggregazione: per creare rapporti di riepilogo ed esaminare i report di riepilogo, utilizza l'API Aggregation Service.
Passaggio 5.1. Utilizzo dell'endpoint createJob per 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 la creazione batch
In Postman, apri "Privacy Sandbox" raccolta e seleziona "createJob".
Seleziona "Corpo". e seleziona "raw" per effettuare il payload della richiesta.
Lo schema del payload createJob è disponibile in github e ha un aspetto 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": "<bucket_name>",
"output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
"output_data_bucket_name": "<bucket_name>",
"job_parameters": {
"output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
"output_domain_bucket_name": "<bucket_name>",
"attribution_report_to": "<reporting origin of report>",
"reporting_site": "<domain of reporting origin(s) of report>", // Only one of attribution_report_to or reporting_site is required as of v2.7.0
"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 dopo che il servizio di aggregazione avrà accettato la richiesta. Altri possibili codici di ritorno sono disponibili nei codici di risposta HTTP.
5.2. Utilizzo dell'endpoint getJob per recuperare lo stato del batch
Per controllare lo stato della richiesta di lavoro, puoi utilizzare l'endpoint getJob. Seleziona "getJob" in "Privacy Sandbox" .
In "Params", aggiorna il valore job_request_id al valore job_request_id inviato nella richiesta createJob.
Il risultato dell'istruzione getJob dovrebbe restituire lo stato della richiesta di job con uno stato HTTP 200. Il "Corpo" della richiesta contiene le informazioni necessarie, come job_status, return_message e error_messages (se il lavoro presenta errori).
Poiché il sito di reporting del report dimostrativo generato è diverso dal sito di onboarding indicato nell'ID AWS, potresti ricevere una risposta con PRIVACY_BUDGET_AUTHORIZATION_ERROR Return_code. Questo è normale poiché nei report il sito dell'origine segnalante non corrisponde a quello 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-dsp.dev",
"reporting_site": "<domain of reporting origin(s) of report>", // Only one of attribution_report_to or reporting_site is required as of v2.7.0
},
"request_processing_started_at": "2023-12-07T22:51:06.034472697Z"
}
5.3. Esaminare il report di riepilogo
Dopo aver 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 formato 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 di valori aggregati per ogni chiave di 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 in output_data_blob_prefix. Il report è in formato AVRO e può essere convertito in un file JSON utilizzando il comando precedente.
Il report contiene la chiave del bucket, la metrica senza rumore e il rumore che viene aggiunto alla metrica senza rumore per formare il report di riepilogo. Il report è simile alla seguente immagine.
Le annotazioni contengono anche in_reports e in_domain, che significa che:
- in_reports: la chiave del bucket è disponibile all'interno dei report aggregabili.
- in_domain: la chiave del bucket è disponibile nel file AVRO output_domain.