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, ya que el almacenamiento compartido almacena los valores y la agregación privada crea los informes agregables.

Público objetivo: Proveedores de tecnología publicitaria y medición.

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. Sin embargo, hay casos de uso 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 se restringe al origen del contexto (el llamador de sharedStorage).

El almacenamiento compartido tiene un límite de capacidad por origen, con cada entrada limitada a una cantidad máxima de caracteres. Si se alcanza el límite, no se almacenarán 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 con JavaScript o encabezados de respuesta. La lectura del almacenamiento compartido solo se produce dentro de un entorno aislado de JavaScript llamado worklet.

Un worklet te permite ejecutar funciones de JavaScript específicas y devolver información al solicitante. Dentro de un worklet, puedes ejecutar JavaScript, pero no puedes interactuar ni comunicarte con la página externa.

Los Worklets se usan para almacenar y extraer datos con la API de Shared Storage.

• 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 se deben completar a través de una worklet de JavaScript. Los métodos que se pueden usar fuera de una worklet de JavaScript se pueden encontrar en Proposed API Surface - Outside the 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.

• Cómo usar encabezados de respuesta

  Al igual que con JavaScript, solo se pueden realizar funciones específicas, como configurar, agregar y borrar valores en el almacenamiento compartido, mediante los encabezados de respuesta. Para trabajar con el almacenamiento compartido en un encabezado de respuesta, se debe incluir Shared-Storage-Writable: ?1 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});
    

  • Usa una etiqueta iframe o img

    <iframe src="https://a.example/path/for/updates" sharedstoragewritable></iframe>
    

  • Usa 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 Shared Storage, llama a sharedStorage.set() desde dentro o fuera de una worklet de JavaScript. Si se realiza una llamada desde fuera de la 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 de la worklet, los datos se escriben en el origen del contexto de navegación que cargó la worklet. Las claves que se configuran tienen una fecha de vencimiento de 30 días a partir de la última actualización.

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

Si se accede al almacenamiento compartido varias veces en la misma carga de página con la misma clave, se reemplaza el valor de la clave. Es conveniente usar sharedStorage.append() si la clave debe mantener el valor anterior.

• Cómo usar 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 de la worklet:

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

• Cómo usar encabezados de respuesta

  También puedes escribir en el almacenamiento compartido con encabezados de respuesta. Para ello, 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
  

  Se pueden separar varios elementos con comas y combinar set, append, delete y clear.

  Shared-Storage-Write :
  set;key="hello";value="world";ignore_if_present, set;key="good";value="bye"
  

Cómo agregar un valor

Puedes adjuntar un valor a una clave existente con el método de adición. Si la clave no existe, llamar a append() crea la clave y establece el valor. Esto se puede lograr con JavaScript o encabezados de respuesta.

• Usar JavaScript

  Para actualizar los valores de las claves existentes, usa sharedStorage.append() dentro o fuera de la 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 agregarlo dentro de la worklet, haz lo siguiente:

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

• Usa encabezados de respuesta

  Al igual que cuando estableces 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"
  

Cómo leer 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 la worklet determina cuyo almacenamiento compartido se lee.

Borrando contenido del almacenamiento compartido

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

• Cómo usar JavaScript

  Para borrar elementos del almacenamiento compartido desde fuera de la worklet, sigue estos pasos:

  window.sharedStorage.delete('myKey');
  

  Para borrar elementos del almacenamiento compartido desde la worklet, haz lo siguiente:

  sharedStorage.delete('myKey');
  

  Para borrar todas las claves a la vez desde fuera del worklet:

  window.sharedStorage.clear();
  

  Para borrar todas las claves a la vez desde dentro de la worklet, haz lo siguiente:

  sharedStorage.clear();
  

• Cómo usar encabezados de respuesta

  Para borrar valores con encabezados de respuesta, también puedes usar Shared-Storage-Write en el encabezado de respuesta para 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 desde 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 incorporador. Por lo tanto, cuando el código de terceros llama a sharedStorage.set(), los datos se escriben en el almacenamiento compartido del incorporador. 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 del iframe. Por lo tanto, la llamada a sharedStorage.set() que se realiza desde el iframe almacena los datos en el almacenamiento compartido del origen del iframe.

Contexto propio

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

Contexto de terceros

Para almacenar el par clave-valor en la tecnología publicitaria o en el contexto de terceros, crea un iframe y llama a set() o delete() en el código JavaScript desde el iframe.

API de Private Aggregation

Para medir los datos agregables almacenados en el almacenamiento compartido, puedes usar la API de PrivateAggregation.

Para crear un informe, llama a contributeToHistogram() dentro de una worklet con un bucket y un valor. El bucket se representa con 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 realizar a una consulta de salida. 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 en todos los intervalos. Si se supera el presupuesto actual, no se generará un informe.

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

Ejecución de Shared Storage y Private Aggregation

Debes crear una tarea para acceder a los datos del almacenamiento compartido. Para ello, llama a createWorklet() con la URL de la worklet. De forma predeterminada, cuando se usa el almacenamiento compartido con createWorklet(), el origen de la partición de datos será el origen del contexto de navegación que realiza la invocación, no el origen de la propia secuencia de comandos de la worklet.

Para cambiar el comportamiento predeterminado, configura la propiedad dataOrigin cuando llames a createWorklet.

• dataOrigin: "context-origin": (Predeterminado) Los datos se almacenan en el almacenamiento compartido del origen del contexto de navegación de invocación.
• dataOrigin: "script-origin": Los datos se almacenan en el almacenamiento compartido del origen de la secuencia de comandos del worklet. Ten en cuenta que debes habilitar este modo.

sharedStorage.createWorklet(scriptUrl, {dataOrigin: "script-origin"});

Para habilitar esta opción, cuando uses "script-origin", el extremo de la secuencia de comandos deberá responder con el encabezado Shared-Storage-Cross-Origin-Worklet-Allowed. Ten en cuenta que CORS debe estar habilitado para las solicitudes entre orígenes.

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1

La configuración de "dataOrigin" en "createWorklet" y la creación de worklets de origen cruzado con "addModule" estuvieron disponibles en M130.

Usa un iframe de origen cruzado

Se necesita un iframe para invocar la worklet de almacenamiento compartido.

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

const sharedStorageWorklet = await window.sharedStorage.createWorklet(
  'https://any-origin.example/modules/sharedStorageWorklet.js'
);
await sharedStorageWorklet.run('shared-storage-report', {
  data: { campaignId: '1234' },
});

En la secuencia de comandos de la worklet, deberás crear una clase con un método run asíncrono y register 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,
      value
    });
  }
}
register('shared-storage-report', SharedStorageReportOperation);

Usa una solicitud de origen cruzado

El almacenamiento compartido y la agregación privada permiten la creación de worklets de origen cruzado sin la necesidad de iframes de origen cruzado.

La página propia también puede invocar una llamada createWorklet() al extremo de JavaScript de origen cruzado. Cuando crees la worklet, deberás establecer el origen de la partición de datos de la worklet como el de script-origin.

async function crossOriginCall() {
  const privateAggregationWorklet = await sharedStorage.createWorklet(
    'https://cross-origin.example/js/worklet.js',
    { dataOrigin: 'script-origin' }
  );
  await privateAggregationWorklet.run('pa-worklet');
}
crossOriginCall();

El extremo de JavaScript de origen cruzado deberá responder con los encabezados Shared-Storage-Cross-Origin-Worklet-Allowed y tener en cuenta que el CORS está habilitado para la solicitud.

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1

Los worklets creados con createWorklet() tendrán selectURL y run(). addModule() no está disponible para esto.

Nota: addModule() se puede usar para crear Worklets de origen cruzado. Sin embargo, se prefiere el uso de createWorklet(), ya que permite la creación de una partición de datos de origen cruzado y puede crear varios worklets, a diferencia de addModule().

class CrossOriginWorklet {
  async run(data){
    // Other code goes here.
    bucket = getBucket(...);
    value = getValue(...);
    privateAggregation.contributeToHistogram({
      bucket,
      value
    });
  }
}

Próximos pasos

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

• Introducción al almacenamiento compartido (Chrome para desarrolladores)
• Casos de uso de almacenamiento compartido (Chrome para desarrolladores)
• Introducción a la agregación privada (Chrome para desarrolladores)
• Explicación del almacenamiento compartido (GitHub)
• Explicación de la agregación privada (GitHub)
• Demo de almacenamiento compartido y agregación privada

Una vez que conozcas las APIs, puedes comenzar a recopilar los informes, que se envían como una solicitud POST a los siguientes extremos como 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 probarlos con la herramienta de pruebas 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.

• Almacenamiento compartido
• Agregación privada