Se usó la API de Cloud Translation para traducir esta página.

Guía de inicio rápido para la implementación del almacenamiento compartido y la agregación privada

Este documento es una guía de inicio rápido para usar el almacenamiento compartido y la agregación privada. Deberás comprender ambas APIs porque Shared Storage almacena los valores, y Private Aggregation crea los informes agregables.

Público objetivo: Proveedores de tecnologías publicitarias y mediciones.

Probar demostración

Prueba la demostración en vivo. Sigue los pasos de las instrucciones de la demostración para habilitar las APIs de Privacy Sandbox. Abrir las Herramientas para desarrolladores de Chrome te ayuda a visualizar los resultados de diferentes casos de uso. Casos de uso disponibles en la demostración:

Agregación privada
- Medición de Unique Reach
- Medición de datos demográficos
- Medición de frecuencia K+
Uso general
- Mide el evento de desplazamiento del cursor dentro de marcos vallados
- Navegación de nivel superior
- Controla dónde pueden escribir los terceros

Cómo ver el almacenamiento compartido

Para ver el contenido almacenado en el almacenamiento compartido, use las Herramientas para desarrolladores de Chrome. Los datos almacenados se pueden encontrar en Application -> Shared Storage.

Ver los datos almacenados en el almacenamiento compartido con las Herramientas para desarrolladores de Chrome

Ver informes de agregación privada

Para ver los informes agregables enviados, navega a chrome://private-aggregation-internals. Cuando el modo de depuración está habilitado, se envía de inmediato (sin retraso) un informe a [[YOUR_ORIGIN]]/.well-known/private-aggregation/debug/report-shared-storage junto con el informe de retraso que se enviará a [[YOUR_ORIGIN]]/.well-known/private-aggregation/report-shared-storage.

Para habilitar la depuración, sigue las instrucciones que se indican en la sección de depuración.

Visualización de informes en chrome://private-aggregation-internals

API de Shared Storage

Para evitar el seguimiento entre sitios, los navegadores comenzaron a particionar todas las formas de almacenamiento, incluido el almacenamiento local, las cookies, etcétera. Pero hay casos prácticos en los que se requiere almacenamiento no particionado. La API de Shared Storage proporciona acceso de escritura ilimitado en diferentes sitios de nivel superior con acceso de lectura que preserva la privacidad.

El almacenamiento compartido está restringido al origen del contexto (el llamador de sharedStorage).

El almacenamiento compartido tiene un límite de capacidad por origen, y cada entrada se limita a una cantidad máxima de caracteres. Si se alcanza el límite, no se almacenan más entradas. Los límites de almacenamiento de datos se describen en la explicación del almacenamiento compartido.

Cómo invocar el almacenamiento compartido

Las tecnologías publicitarias pueden escribir en el almacenamiento compartido usando JavaScript o encabezados de respuesta. La lectura desde el almacenamiento compartido solo ocurre dentro de un entorno aislado de JavaScript llamado worklet.

Con JavaScript: Las tecnologías publicitarias pueden realizar funciones específicas de almacenamiento compartido, como configurar, agregar y borrar valores fuera de un worklet de JavaScript. Sin embargo, las funciones como leer el almacenamiento compartido y realizar la agregación privada deben completarse a través de un worklet de JavaScript. Los métodos que se pueden usar fuera de un worklet de JavaScript se pueden encontrar en Superficie de API propuesta: fuera del worklet.

Los métodos que se usan en el worklet durante una operación se pueden encontrar en Superficie de API propuesta: en el worklet.
Usa encabezados de respuesta

Esta función está disponible en M119.

Al igual que JavaScript, solo se pueden usar funciones específicas, como configurar, agregar y borrar valores en el almacenamiento compartido, mediante encabezados de respuesta. Para trabajar con el almacenamiento compartido en un encabezado de respuesta, Shared-Storage-Writable: ?1 debe incluirse en el encabezado de la solicitud.

Para iniciar una solicitud desde el cliente, ejecuta el siguiente código, según el método que hayas elegido:
- Usa fetch()
```
fetch("https://a.example/path/for/updates", {sharedStorageWritable: true});
```
- Con una etiqueta iframe o img
```
<iframe src="https://a.example/path/for/updates" sharedstoragewritable></iframe>
```
- Cómo usar un atributo IDL con una etiqueta iframe o img
```
let iframe = document.getElementById("my-iframe");
iframe.sharedStorageWritable = true;
iframe.src = "https://a.example/path/for/updates";
```

Puedes encontrar más información en Almacenamiento compartido: encabezados de respuesta.

Cómo escribir en el almacenamiento compartido

Para escribir en el almacenamiento compartido, llama a sharedStorage.set() desde dentro o fuera de un worklet de JavaScript. Si se llama desde fuera del worklet, los datos se escriben en el origen del contexto de navegación desde el que se realizó la llamada. Si se llama desde dentro del worklet, los datos se escriben en el origen del contexto de navegación que lo cargó. Las claves configuradas tienen una fecha de vencimiento de 30 días desde la última actualización.

El campo ignoreIfPresent es opcional. Si está presente y se configura como true, la clave no se actualiza si ya existe. El vencimiento de la clave se renueva a 30 días desde la llamada a set(), incluso si la clave no se actualiza.

Si se accede a almacenamiento compartido varias veces en la misma carga de página con la misma clave, se reemplaza el valor de la clave. Se recomienda usar sharedStorage.append() si la clave necesita mantener el valor anterior.

Usa JavaScript

Fuera del worklet:

window.sharedStorage.set('myKey', 'myValue1', { ignoreIfPresent: true });
// Shared Storage: {'myKey': 'myValue1'}
window.sharedStorage.set('myKey', 'myValue2', { ignoreIfPresent: true });
// Shared Storage: {'myKey': 'myValue1'}
window.sharedStorage.set('myKey', 'myValue2', { ignoreIfPresent: false });
// Shared Storage: {'myKey': 'myValue2'}

Del mismo modo, dentro del worklet:

sharedStorage.set('myKey', 'myValue1', { ignoreIfPresent: true });

Usa encabezados de respuesta

También puedes escribir en el almacenamiento compartido usando encabezados de respuesta. Para hacerlo, usa Shared-Storage-Write en el encabezado de respuesta junto con los siguientes comandos:
```
Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present
```
```
Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present=?0
```
Varios elementos se pueden separar por comas y se pueden combinar set, append, delete y clear.
```
Shared-Storage-Write : 
set;key="hello";value="world";ignore_if_present, set;key="good";value="bye"
```

Agrega un valor

Puedes agregar un valor a una clave existente con el método de anexo. Si la clave no existe, cuando se llama a append(), se crea la clave y se establece el valor. Esto se puede lograr con JavaScript o encabezados de respuesta.

Usa JavaScript

Para actualizar los valores de claves existentes, usa sharedStorage.append() desde dentro o fuera del worklet.

window.sharedStorage.append('myKey', 'myValue1');
// Shared Storage: {'myKey': 'myValue1'}
window.sharedStorage.append('myKey', 'myValue2');
// Shared Storage: {'myKey': 'myValue1myValue2'}
window.sharedStorage.append('anotherKey', 'hello');
// Shared Storage: {'myKey': 'myValue1myValue2', 'anotherKey': 'hello'}

Para adjuntar dentro del worklet, haz lo siguiente:

sharedStorage.append('myKey', 'myValue1');

Usa encabezados de respuesta

Al igual que cuando configuras un valor en el almacenamiento compartido, puedes usar Shared-Storage-Write en el encabezado de respuesta para pasar el par clave-valor.
```
Shared-Storage-Write : append;key="myKey";value="myValue2"
```

Lee desde el almacenamiento compartido

Solo puedes leer desde el almacenamiento compartido desde un worklet.

await sharedStorage.get('mykey');

El origen del contexto de navegación desde el que se cargó el módulo de worklet determina de qué almacenamiento compartido se lee.

Borrar del almacenamiento compartido

Puedes borrar desde el almacenamiento compartido mediante JavaScript desde el interior o el exterior del worklet o usando encabezados de respuesta con delete(). Para borrar todas las claves a la vez, usa clear() de cualquiera de ellas.

Usa JavaScript

Para borrar datos del almacenamiento compartido desde fuera del worklet, haz lo siguiente:
```
window.sharedStorage.delete('myKey');
```
Para borrar del almacenamiento compartido desde el worklet, haz lo siguiente:
```
sharedStorage.delete('myKey');
```
Para borrar todas las claves a la vez desde fuera del worklet:
```
window.sharedStorage.clear();
```
Sigue estos pasos para borrar todas las claves a la vez desde dentro del worklet:
```
sharedStorage.clear();
```
Usa encabezados de respuesta

Para borrar valores mediante encabezados de respuesta, también puedes usar Shared-Storage-Write en el encabezado de respuesta a fin de pasar la clave que se borrará.
```
delete;key="myKey"
```
Para borrar todas las claves con encabezados de respuesta, haz lo siguiente:
```
clear;
```

Cambio de contexto

Los datos de almacenamiento compartido se escriben en el origen (por ejemplo, https://example.adtech.com) del contexto de navegación en el que se originó la llamada.

Cuando cargas el código de terceros con una etiqueta <script>, el código se ejecuta en el contexto de navegación del incorporado. Por lo tanto, cuando el código del tercero llama a sharedStorage.set(), los datos se escriben en el almacenamiento compartido de la incorporaciones. Cuando cargas el código de terceros dentro de un iframe, el código recibe un nuevo contexto de navegación, y su origen es el origen del iframe. Por lo tanto, la llamada a sharedStorage.set() realizada desde el iframe almacena los datos en el almacenamiento compartido del origen del iframe.

Contexto propio

Si una página propia tiene incorporado código JavaScript de terceros que llama a sharedStorage.set() o sharedStorage.delete(), el par clave-valor se almacena en el contexto propio.

Datos almacenados en una página propia con JavaScript de terceros incorporado.

Contexto de terceros

El par clave-valor se puede almacenar en el contexto de tecnología publicitaria o de terceros creando un iframe y llamando a set() o delete() en el código JavaScript desde el iframe.

Datos almacenados en un contexto de tecnología publicitaria o de terceros

API de Private Aggregation

Para medir los datos agregables que se almacenan en el almacenamiento compartido, puedes usar la API de Private Aggregation.

Para crear un informe, llama a contributeToHistogram() dentro de un worklet con un bucket y un valor. El bucket está representado por un número entero de 128 bits sin firma que se debe pasar a la función como un BigInt. El valor es un número entero positivo.

Para proteger la privacidad, la carga útil del informe, que contiene el bucket y el valor, se encripta en tránsito, y solo se puede desencriptar y agregar con el servicio de agregación.

El navegador también limitará las contribuciones que un sitio puede hacer a una búsqueda resultante. Específicamente, el presupuesto de contribución limita el total de todos los informes de un solo sitio para un navegador determinado en un período determinado y e incluye todos los buckets. Si se supera el presupuesto actual, no se generará un informe.

privateAggregation.contributeToHistogram({
  bucket: BigInt(myBucket),
  value: parseInt(myBucketValue)
});

Ejecución del almacenamiento compartido y la agregación privada

En el iframe del anuncio, llama a addModule() para cargar el módulo de worklet. Para ejecutar el método que está registrado en el archivo de worklet sharedStorageWorklet.js, en el mismo iframe del anuncio JavaScript, llama a sharedStorage.run().

await window.sharedStorage.worklet.addModule('modules/sharedStorageWorklet.js');
await window.sharedStorage.worklet.run('shared-storage-report', {
  data: { campaignId: '1234' },
});

En la secuencia de comandos del worklet, deberás crear una clase con un método run asíncrono. Y register esta clase para que se ejecute en el iframe del anuncio. Dentro de sharedStorageWorklet.js:

class SharedStorageReportOperation {
  async run(data) {
    // Other code goes here.
    bucket = getBucket(...);
    value = getValue(...);
    privateAggregation.contributeToHistogram({
      bucket: bucket,
      value: value
    });
  }
}
register('shared-storage-report',
  SharedStorageReportOperation);

Depuración

Para habilitar la depuración, llama al método enableDebugMode() de JavaScript en el mismo contexto en el que se usa el almacenamiento compartido y la agregación privada. Esto se aplicará a los informes futuros en el mismo contexto.

privateAggregation.enableDebugMode();

Para asociar los informes con los contextos que los activaron, puedes configurar una clave de depuración de número entero sin firma de 64 bits que se pase a la llamada de JavaScript. El debugKey es un BigInt.

privateAggregation.enableDebugMode({debugKey: 1234});

Cómo depurar el almacenamiento compartido

Shared Storage muestra un mensaje de error genérico:

Promise is rejected without and explicit error message

Puedes depurar el almacenamiento compartido si unes las llamadas con bloques try-catch.

try {
  privateAggregation.contributeToHistogram({bucket, value});
} catch (e){
  console.log(e);
}

Depurar agregación privada

Los informes se envían a /.well-known/private-aggregation/report-shared-storage y /.well-known/private-aggregation/debug/report-shared-storage. Los informes de depuración reciben una carga útil similar a la siguiente JSON. Esta carga útil define el campo api como “almacenamiento compartido”.

{
   "aggregation_coordinator_identifier": "aws-cloud",
   "aggregation_service_payloads": [ {
      "debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAEfV32BFWlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "9bc4afa7-2934-4779-99ff-999d91b137ec",
      "payload": "bqOFO/cHCdwefU2W4FjMYRMSLoGHPWwZbgVF4aa/ji2YtwFz+jb6v2XCwQUdmvYcZSRPKosGRpKELJ0xAFv+VBYvCiv3FXP6jjAHQD+XAJUz17A39aXijk6JnEAu86+DfTSbXYn1fWhGzIG9xH/Y"
   } ],
   "debug_key": "1234",
   "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"93f86829-cdf7-4ecd-b16d-4e415a3ee063\",\"reporting_origin\":\"https://small-free-wealth.glitch.me\",\"scheduled_report_time\":\"1681319668\",\"version\":\"0.1\"}"
}

Depurar carga útil de texto simple

El debug_cleartext_payload está codificado en CBOR Base64. Puedes ver el bucket y el valor con el decodificador o usar el código JavaScript que se encuentra en el decodificador de almacenamiento compartido.

Próximos pasos

En las siguientes páginas, se explican aspectos importantes de las APIs de Shared Storage y Private Aggregation.

Una vez que te familiarices con las APIs, puedes comenzar a recopilar los informes, que se envían como una solicitud POST a los siguientes extremos en formato JSON en el cuerpo de la solicitud.

Informes de depuración: context-origin/.well-known/private-aggregation/debug/report-shared-storage
Informes: context-origin/.well-known/private-aggregation/report-shared-storage

Una vez que se recopilan los informes, puedes realizar pruebas con la herramienta de prueba local o configurar el entorno de ejecución confiable para el servicio de agregación a fin de obtener los informes agregados.

Comparte tus comentarios

Puedes compartir tus comentarios sobre las APIs y la documentación en GitHub.