Guia de início rápido para implementação do armazenamento compartilhado e da agregação particular

Este documento é um guia de início rápido para usar o armazenamento compartilhado e a agregação particular. Você precisa entender as duas APIs porque o armazenamento compartilhado armazena os valores e a agregação privada cria os relatórios agregáveis.

Público-alvo:adtechs e provedores de medição.

Confira a demonstração

Teste a demonstração ao vivo. Siga as etapas nas instruções da demonstração para ativar as APIs do Sandbox de privacidade. Abrir o Chrome DevTools ajuda a visualizar os resultados de diferentes casos de uso. Casos de uso disponíveis na demonstração:

• Agregação particular
  • Medição do Unique Reach
  • Medição de informações demográficas
  • Medição de frequência K+
• Uso geral
  • Medir o evento de passar o cursor dentro de frames delimitados
  • Navegação de nível superior
  • Como controlar onde terceiros podem gravar

Como acessar o armazenamento compartilhado

Para conferir o que está no armazenamento compartilhado, use o Chrome DevTools. Os dados armazenados podem ser encontrados em Application -> Shared Storage.

Mostrar relatórios sobre a agregação particular

Para conferir os relatórios agregáveis enviados, navegue até chrome://private-aggregation-internals. Quando o modo de depuração está ativado, um relatório é enviado imediatamente (sem atraso) para [[YOUR_ORIGIN]]/.well-known/private-aggregation/debug/report-shared-storage com o relatório com atraso que é enviado para [[YOUR_ORIGIN]]/.well-known/private-aggregation/report-shared-storage.

Para ativar a depuração, siga as instruções na seção de depuração.

API Shared Storage

Para evitar o rastreamento entre sites, os navegadores começaram a particionar todas as formas de armazenamento, incluindo armazenamento local, cookies e assim por diante. Mas há casos de uso em que o armazenamento não particionado é necessário. A API Shared Storage fornece acesso de gravação ilimitado em diferentes sites de nível superior com acesso de leitura que preserva a privacidade.

O armazenamento compartilhado é restrito à origem do contexto (o autor da chamada de sharedStorage).

O armazenamento compartilhado tem um limite de capacidade por origem, com cada entrada limitada a um número máximo de caracteres. Se o limite for atingido, nenhuma outra entrada será armazenada. Os limites de armazenamento de dados são descritos na explicação sobre o armazenamento compartilhado.

Como invocar o armazenamento compartilhado

As adtechs podem gravar no armazenamento compartilhado usando JavaScript ou cabeçalhos de resposta. A leitura do armazenamento compartilhado ocorre apenas em um ambiente JavaScript isolado chamado worklet.

Um worklet permite executar funções JavaScript específicas e retornar informações ao solicitante. Em um worklet, é possível executar JavaScript, mas não é possível interagir ou se comunicar com a página externa.

Os Worklets são usados para armazenar e extrair dados com a API Shared Storage.

• Como usar JavaScript As adtechs podem executar funções específicas de armazenamento compartilhado, como configurar, anexar e excluir valores fora de uma worklet do JavaScript. No entanto, funções como a leitura do armazenamento compartilhado e a execução da agregação privada precisam ser concluídas por uma worklet do JavaScript. Os métodos que podem ser usados fora de um worklet JavaScript podem ser encontrados em Superfície de API proposta: fora do worklet.

  Os métodos usados na worklet durante uma operação podem ser encontrados em Superfície de API proposta: na worklet.

• Como usar cabeçalhos de resposta

  Esse recurso foi disponibilizado na versão M119.

  Assim como o JavaScript, apenas funções específicas, como definir, anexar e excluir valores no armazenamento compartilhado, podem ser feitas usando cabeçalhos de resposta. Para trabalhar com o armazenamento compartilhado em um cabeçalho de resposta, Shared-Storage-Writable: ?1 precisa ser incluído no cabeçalho da solicitação.

  Para iniciar uma solicitação do cliente, execute o código a seguir, dependendo do método escolhido:

  • Como usar o fetch()

    fetch("https://a.example/path/for/updates", {sharedStorageWritable: true});
    

  • Como usar uma tag iframe ou img

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

  • Como usar um atributo IDL com uma tag iframe ou img

    let iframe = document.getElementById("my-iframe");
    iframe.sharedStorageWritable = true;
    iframe.src = "https://a.example/path/for/updates";
    

Mais informações podem ser encontradas em Armazenamento compartilhado: cabeçalhos de resposta.

Como gravar no armazenamento compartilhado

Para gravar no armazenamento compartilhado, chame sharedStorage.set() de dentro ou fora de um worklet JavaScript. Se chamados de fora da worklet, os dados são gravados na origem do contexto de navegação do qual a chamada foi feita. Se chamados de dentro do worklet, os dados são gravados na origem do contexto de navegação que o carregou. As chaves definidas têm uma data de validade de 30 dias a partir da última atualização.

O campo ignoreIfPresent é opcional. Se presente e definida como true, a chave não será atualizada (se já existir). A expiração da chave é renovada para 30 dias a partir da chamada set(), mesmo que a chave não seja atualizada.

Se o armazenamento compartilhado for acessado várias vezes no mesmo carregamento de página com a mesma chave, o valor dela será substituído. É recomendável usar sharedStorage.append() se a chave precisar manter o valor anterior.

• Com JavaScript

  Fora da 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'}
  

  Da mesma forma, dentro da worklet:

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

• Como usar cabeçalhos de resposta

  Também é possível gravar no armazenamento compartilhado usando cabeçalhos de resposta. Para fazer isso, use Shared-Storage-Write no cabeçalho de resposta com os seguintes comandos:

  Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present
  

  Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present=?0
  

  Vários itens podem ser separados por vírgula e combinar set, append, delete e clear.

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

Como anexar um valor

É possível anexar um valor a uma chave atual usando o método de anexação. Se a chave não existir, chamar append() criará a chave e definirá o valor. Isso pode ser feito usando JavaScript ou cabeçalhos de resposta.

• Com JavaScript

  Para atualizar valores de chaves existentes, use sharedStorage.append() de dentro ou fora da 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 anexar dentro da worklet:

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

• Como usar cabeçalhos de resposta

  Assim como na definição de um valor no armazenamento compartilhado, é possível usar o Shared-Storage-Write no cabeçalho de resposta para transmitir o par de chave-valor.

  Shared-Storage-Write : append;key="myKey";value="myValue2"
  

Como ler do armazenamento compartilhado

Só é possível fazer a leitura no armazenamento compartilhado de dentro de um worklet.

await sharedStorage.get('mykey');

A origem do contexto de navegação do qual o módulo de worklet foi carregado determina qual armazenamento compartilhado é lido.

Como excluir do armazenamento compartilhado

É possível realizar exclusões do armazenamento compartilhado usando o JavaScript de dentro ou fora da worklet ou usando cabeçalhos de resposta com delete(). Para excluir todas as chaves de uma só vez, use clear() de qualquer uma delas.

• Com JavaScript

  Para excluir do armazenamento compartilhado de fora do worklet:

  window.sharedStorage.delete('myKey');
  

  Para excluir do armazenamento compartilhado de dentro do worklet:

  sharedStorage.delete('myKey');
  

  Para excluir todas as chaves de fora da worklet de uma só vez:

  window.sharedStorage.clear();
  

  Para excluir todas as chaves de uma vez de dentro do worklet:

  sharedStorage.clear();
  

• Como usar cabeçalhos de resposta

  Para excluir valores usando cabeçalhos de resposta, também é possível usar Shared-Storage-Write no cabeçalho de resposta para passar a chave a ser excluída.

  delete;key="myKey"
  

  Para excluir todas as chaves usando cabeçalhos de resposta:

  clear;
  

Mudança de contexto

Os dados de armazenamento compartilhado são gravados na origem (por exemplo, https://example.adtech.com) do contexto de navegação que originou a chamada.

Quando você carrega o código de terceiros usando uma tag <script>, o código é executado no contexto de navegação do incorporador. Portanto, quando o código de terceiros chama sharedStorage.set(), os dados são gravados no Armazenamento compartilhado do incorporador. Quando você carrega o código de terceiros em um iframe, ele recebe um novo contexto de navegação, e a origem dele é a do iframe. Portanto, a chamada sharedStorage.set() feita do iframe armazena os dados no armazenamento compartilhado da origem do iframe.

Contexto próprio

Se uma página própria tiver um código JavaScript de terceiros incorporado que chama sharedStorage.set() ou sharedStorage.delete(), o par de chave-valor será armazenado no contexto próprio.

Contexto de terceiros

O par de chave-valor pode ser armazenado no contexto da adtech ou de terceiros criando um iframe e chamando set() ou delete() no código JavaScript no iframe.

API Private Aggregate

Para medir dados agregáveis armazenados no armazenamento compartilhado, é possível usar a API Private Agregação.

Para criar um relatório, chame contributeToHistogram() dentro de um worklet com um bucket e um valor. O bucket é representado por um número inteiro de 128 bits não assinado que precisa ser transmitido para a função como um BigInt. O valor é um número inteiro positivo.

Para proteger a privacidade, o payload do relatório, que contém o bucket e o valor, é criptografado em trânsito e só pode ser descriptografado e agregado usando o serviço de agregação.

O navegador também limitará as contribuições que um site pode fazer a uma consulta de saída. Especificamente, o orçamento de contribuição limita o total de todos os relatórios de um único site para um determinado navegador em um determinado período em todos os buckets. Se o orçamento atual for excedido, um relatório não será gerado.

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

Como executar o armazenamento compartilhado e a agregação privada

No iframe do anúncio, carregue o módulo worklet chamando addModule(). Para executar o método registrado no arquivo de worklet sharedStorageWorklet.js, no mesmo JavaScript do iframe do anúncio, chame sharedStorage.run().

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

No script de worklet, você precisará criar uma classe com um método run assíncrono. E register essa classe será executada no iframe do anúncio. 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);

Depuração

Para ativar a depuração, chame o método JavaScript enableDebugMode() no mesmo contexto em que o armazenamento compartilhado e a agregação privada são usados. Ele será aplicado a relatórios futuros no mesmo contexto.

privateAggregation.enableDebugMode();

Para associar os relatórios aos contextos que os acionaram, defina uma chave de depuração de número inteiro não assinado de 64 bits que é transmitida para a chamada JavaScript. O debugKey é um BigInt.

privateAggregation.enableDebugMode({debugKey: 1234});

Como depurar armazenamento compartilhado

O armazenamento compartilhado retorna uma mensagem de erro genérica:

Promise is rejected without and explicit error message

Para depurar o armazenamento compartilhado, una as chamadas com blocos try-catch.

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

Como depurar a agregação particular

Os relatórios são enviados para /.well-known/private-aggregation/report-shared-storage e /.well-known/private-aggregation/debug/report-shared-storage. Os relatórios de depuração recebem um payload semelhante ao JSON a seguir. Esse payload define o campo api como "shared-storage".

{
   "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 payload de texto não criptografado

O debug_cleartext_payload é codificado em Base64 CBOR. É possível visualizar o bucket e o valor usando o decodificador ou o código JavaScript encontrado no decodificador de armazenamento compartilhado.

Próximas etapas

As páginas a seguir explicam aspectos importantes das APIs de armazenamento compartilhado e agregação privada.

• Introdução ao armazenamento compartilhado (desenvolvedor do Chrome)
• Casos de uso de armazenamento compartilhado (desenvolvedor do Chrome)
• Introdução à agregação particular (desenvolvedor do Chrome)
• Explicação sobre o armazenamento compartilhado (GitHub)
• Explicação sobre agregação privada (GitHub)
• Demonstração de armazenamento compartilhado e agregação privada

Depois de se familiarizar com as APIs, comece a coletar os relatórios, que são enviados como uma solicitação POST para os seguintes endpoints como JSON no corpo da solicitação.

• Relatórios de depuração: context-origin/.well-known/private-aggregation/debug/report-shared-storage
• Relatórios - context-origin/.well-known/private-aggregation/report-shared-storage

Depois que os relatórios forem coletados, é possível testar usando a ferramenta de teste local ou configurar o ambiente de execução confiável para o serviço de agregação para ver os relatórios agregados.

Envie feedback

Compartilhe seu feedback sobre as APIs e a documentação no GitHub.

• Armazenamento compartilhado
• Agregação particular