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 utilizar el almacenamiento compartido y los Agregación. Deberás conocer 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

Probar la demostración

Prueba la demostración en vivo. Sigue los pasos en las instrucciones de demostración para habilitar las APIs de Privacy Sandbox. Abriendo Chrome Herramientas para desarrolladores 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 colocar el cursor sobre un elemento dentro de marcos vallados
  • Navegación de nivel superior
  • Controlar dónde pueden escribir los terceros

Cómo ver el almacenamiento compartido

Para ver lo que está almacenado en el almacenamiento compartido, usa las Herramientas para desarrolladores de Chrome. Los datos almacenados pueden se encuentran en Application -> Shared Storage.

Ver informes de agregación privada

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

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

API de Shared Storage

Para evitar el seguimiento entre sitios, los navegadores comenzaron a particionar todas las formas de de almacenamiento, incluido el almacenamiento local, las cookies, etcétera. Pero 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 funciones que preservan la privacidad acceso de lectura.

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

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

Cómo invocar el almacenamiento compartido

Las tecnologías publicitarias pueden escribir en el almacenamiento compartido mediante JavaScript o encabezados de respuesta. La lectura del almacenamiento compartido solo ocurre dentro de un JavaScript aislado 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 JavaScript worklet. Sin embargo, las funciones como leer el almacenamiento compartido y realizar La agregación privada se debe completar a través de un worklet de JavaScript. Los métodos que pueden usarse fuera de un worklet de JavaScript se pueden encontrar en Plataforma de API propuesta: Fuera del worklet.

  Los métodos que se usan en el worklet durante una operación se pueden encontrar en La superficie de API propuesta: en el worklet.

• Usa encabezados de respuesta

  Esta función está disponible a partir de la versión M119.

  De manera similar a JavaScript, solo se pueden usar funciones específicas, como configuración, adición, y borrar valores en el almacenamiento compartido se puede usar con encabezados de respuesta. Para funcionan 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 del cliente, ejecuta el siguiente código, según el método que elijas:

  • 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 obtener más información en el artículo Almacenamiento compartido: Respuesta. Encabezados

Cómo escribir en el almacenamiento compartido

Para escribir en el almacenamiento compartido, llama a sharedStorage.set() desde o desde 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 cargó el worklet. Las claves que se configuran tienen una fecha de vencimiento de 30 días desde 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 del la llamada a set(), incluso si no se actualiza la clave

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

• 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'}
  

  De manera similar, dentro del worklet, haz lo siguiente:

  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 lo siguiente 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 con comas y pueden 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 agregar un valor a una clave existente con el método agregado. Si la clave no existe, llamar a append() crea la clave y establece el valor. Esto puede lograrse con JavaScript o con encabezados de respuesta.

• Usar JavaScript

  Para actualizar los valores de las claves existentes, usa sharedStorage.append() desde cualquiera de los dos métodos: 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 adjuntarlo 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 la 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 del worklet. determina de quién es el almacenamiento compartido que se lee.

Borrando contenido del almacenamiento compartido

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

• Usar JavaScript

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

  window.sharedStorage.delete('myKey');
  

  Para borrar del almacenamiento compartido desde el worklet, sigue estos pasos:

  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 el worklet, haz lo siguiente:

  sharedStorage.clear();
  

• Usa 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 mediante encabezados de respuesta, haz lo siguiente:

  clear;
  

Cambio de contexto

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

Cuando cargas el código de terceros con una etiqueta <script>, se ejecuta el código. en el contexto de navegación de la incorporación. Por lo tanto, cuando el código de terceros llama a sharedStorage.set(), los datos se escriben en el directorio compartido Almacenamiento. Cuando cargas el código de terceros en 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 código JavaScript de terceros incorporado que llama sharedStorage.set() o sharedStorage.delete(), el par clave-valor se almacena. en un contexto propio.

Contexto de terceros

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

API de Private Aggregation

Para medir datos agregables almacenados en el almacenamiento compartido, puedes usar el API de Aggregation.

Para crear un informe, llama a contributeToHistogram() dentro de un worklet con un bucket y valor. El bucket está representado por un número entero de 128 bits sin firma que se debe pasar a la función como 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 durante el envío y solo se puede desencriptar y agregar con el Servicio de agregación.

El navegador también limitará las contribuciones que puede hacer un sitio a un archivo de salida. para cada búsqueda. Específicamente, la contribución presupuesto limita el total de todos los informes de un solo sitio para un navegador determinado en una una ventana de tiempo determinada en todos los segmentos. Si se excede el presupuesto actual, se no se generará el informe.

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

Cómo ejecutar el almacenamiento compartido y la agregación privada

Cómo usar iframe de origen cruzado

Se necesita un iframe para invocar el worklet del almacenamiento compartido.

En el iframe del anuncio, llama a addModule() para cargar el módulo del worklet. Para ejecutar método registrado en el archivo de worklet sharedStorageWorklet.js, en mismo iframe de JavaScript de anuncio, 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 run asíncrono. . Agrega register para que esta clase se ejecute en el iframe del anuncio. Interior 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);

Usa solicitudes 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 puede invocar una llamada createWorklet() al origen cruzado. extremo de JavaScript.

async function crossOriginCall() {
  let privateAggregationWorklet = await sharedStorage.createWorklet(
    'https://cross-origin.dev/js/worklet.js',
  );
  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 permitir el origen cruzado mediante Access-Control-Allow-Origin

Advertencia: Los encabezados de respuesta de la secuencia de comandos del worklet deberán habilitar esta opción con CORS Access-Control-Allow-Origin y Shared-Storage-Cross-Origin-Worklet-Allowed. Ten cuidado al proporcionar acceso al worklet, ya que no es el documento el que solicita worklet.

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1
Access-Control-Allow-Origin : https://first-party.dev

Los Worklets creados con createWorklet() tendrán selectURL y run(). addModule() no está disponible para esta opción.

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

Depuración

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

privateAggregation.enableDebugMode();

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

privateAggregation.enableDebugMode({debugKey: 1234});

Cómo depurar el almacenamiento compartido

El almacenamiento compartido muestra un mensaje de error genérico:

Promise is rejected without and explicit error message

Puedes depurar el almacenamiento compartido uniendo las llamadas con prueba-captura bloques.

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

Depura la 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 Informes de depuración recibir una carga útil similar a la siguiente JSON. Esta carga útil define el api como “shared-storage”.

{
   "aggregation_coordinator_origin": "https://publickeyservice.msmt.gcp.privacysandboxservices.com",
   "aggregation_service_payloads": [ {
      "debug_cleartext_payload": "omRkYXRhlKJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAB1vNFaJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAGlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "1569ab37-da44-4a26-80d9-5ed6524ab2a7",
      "payload": "/9nHrWn1MnJWRxFvanbubciWE9mPyIij6uYLi5k351eQCd3/TZpe2knaatUNcniq4a4e61tmKebv50OmMRZFnnCfcAwIdIgLHu1a3en97PojqWJBfO52RiVMIcP7KQTLzMxq2LhvPSdV4zjXo1Teu/JuIK3LIyis3vUMpS+tUAX0QV+I6X5SVmZFiNW9aMb8DwLOtqrBy5JJ/EkOIY0G+1Fi1/3R7UtKsqM1o71A/OzdmlNkwO7EV/VUNinGvWnd19FvDHe/kqkNdTHKbhAnMmbZzHW9bsEQS81leElCla6BTdbdbeeFU/jbTj0AOaoNOIe5r7FU5NG6nW4ULXTCbLLjTQ1mtl3id3IP41Zin1JvABCDC/HUSgLFz8EUqkmbMIOlMfNYA79aURq6FqE0GO0HtICYf0GPNdVv7p4jY3FNn6+JS4l5F3t+3lP9ceo4IpCE+31jzMtYJ+19xFh6C5ufteBR/iknZFcc1w3caQBhgRl5jt8DbaOzYcW4690H8Ul4Oh2wRO+6/njifk+pExLay/O5swLi2lUUph5OUEaaztwwzh2mnhwIBxMkPnfsGihiF+5KDEajVfMZ3NLsIDoZO+l4RTZrkqE+jVkAqaZGBiCIx42Edp/JV0DXfrryypCdQBZr8iEbSzCM9hKsMfLN7S/VkPe5rDwOZbhKCn5XXgfGz5tSx/KbZgsQf4OCEhwAyNPHAh3MHU7xmkQ3pKg4EIUC/WOtKAlVDOtDMmPPoQY1eAwJhw9SxZaYF1kHjUkTm3EnGhgXgOwCRWqeboNenSFaCyp6DbFNI3+ImONMi2oswrrZO+54Tyhca5mnLIiInI+C3SlP4Sv1jFECIUdf/mifJRM5hMj6OChzHf4sEifjqtD4A30c4OzGexWarie2xakdQej9Go4Lm0GZEDBfcAdWLT9HwmpeI2u4HDAblXDvLN8jYFDOOtzOl90oU7AwdhkumUCFLRadXAccXW9SvLfDswRkXMffMJLFqkRKVE1GPonFFtlzaRqp7IgE8L6AOtz6NDcxAjHnEuzDPPMcWMl1AFH0gq7h"
   } ],
   "debug_key": "1234",
   "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"80d93c0a-a94e-4ab7-aeb5-a4ecd4bfc598\",\"reporting_origin\":\"https://privacy-sandbox-demos-dsp.dev\",\"scheduled_report_time\":\"1717784740\",\"version\":\"0.1\"}"
}

Depura la carga útil de texto simple

La debug_cleartext_payload es Base64 Codificación CBOR. Puedes ver el bucket y valor con el decodificador o usa el código JavaScript que se encuentra en el Almacenamiento compartido decodificador.

Próximos pasos

En las siguientes páginas, se explican aspectos importantes de las políticas de almacenamiento compartido y de agregación.

• 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 agregación privada (GitHub)
• Demostración de almacenamiento compartido y agregación privada

Una vez que te familiarices con las APIs, puedes comenzar a recopilar los informes, enviados como una solicitud POST a los siguientes extremos como JSON en el del 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 recopilados los informes, puedes realizar pruebas con las pruebas locales herramienta o configurar el entorno de ejecución confiable para la agregación Servicio para 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