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 sobre como usar o armazenamento compartilhado e Agregação. Você vai precisar 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.

Teste a demonstração

Confira a demonstração ao vivo. Siga as etapas nas instruções da demonstração para ativar as APIs do Sandbox de privacidade. Abrindo o Chrome O 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 ao passar o cursor dentro de frames isolados
  • Navegação de nível superior
  • Como controlar onde terceiros podem gravar

Como acessar o armazenamento compartilhado

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

Ver relatórios sobre agregação privada

Para conferir os relatórios agregáveis enviados, acesse 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 junto do relatório de tempo de atraso a ser enviado ao [[YOUR_ORIGIN]]/.well-known/private-aggregation/report-shared-storage.

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

API Shared Storage

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

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

O armazenamento compartilhado tem um limite de capacidade por origem, e cada entrada é limitada a um máximo de caracteres. Se o limite for atingido, nenhuma outra entrada será armazenados. Os limites de armazenamento de dados são descritos em Armazenamento compartilhado de explicação.

Como invocar armazenamento compartilhado

As adtechs podem gravar no armazenamento compartilhado usando JavaScript ou cabeçalhos de resposta. A leitura de um armazenamento compartilhado ocorre apenas em um 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 definir, anexar e excluir valores fora de uma regra worklet. No entanto, funções como a leitura do armazenamento compartilhado e a execução A agregação particular precisa ser concluída com um worklet JavaScript. 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 no worklet durante uma operação podem ser encontrados em Superfície de API proposta - no worklet.

• Como usar cabeçalhos de resposta

  Esse recurso foi disponibilizado na versão M119.

  Semelhante ao JavaScript, apenas funções específicas como configuração, anexação, e a exclusão de valores no armazenamento compartilhado pode ser feita usando cabeçalhos de resposta. Para trabalhar com 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 o método escolhido:

  • Como usar o fetch()

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

  • Usar uma tag iframe ou img

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

  • 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: resposta Cabeçalhos.

Como gravar no armazenamento compartilhado

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

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

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

• Usando JavaScript

  Fora do 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 do worklet:

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

• Como usar cabeçalhos de resposta

  Você também pode gravar no armazenamento compartilhado usando cabeçalhos de resposta. Para isso, use Shared-Storage-Write no cabeçalho de resposta com o seguinte 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"
  

Anexar um valor

É possível acrescentar um valor a uma chave existente usando o método de anexação. Se a chave não existe, chamar append() cria a chave e define o valor. Isso pode ser realizada usando JavaScript ou cabeçalhos de resposta.

• Usando JavaScript

  Para atualizar os valores de chaves existentes, use sharedStorage.append() de dentro ou fora dele.

  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 do worklet:

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

• Como usar cabeçalhos de resposta

  Semelhante à definição de um valor no armazenamento compartilhado, é possível usar o método 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 ler dados do Armazenamento compartilhado em um worklet.

await sharedStorage.get('mykey');

A origem do contexto de navegação de onde o módulo do worklet foi carregado determina de quem é o armazenamento compartilhado que será lido.

Excluir do armazenamento compartilhado

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

• Usando 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 uma só vez de fora do worklet:

  window.sharedStorage.clear();
  

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

  sharedStorage.clear();
  

• Como usar cabeçalhos de resposta

  Para excluir valores usando cabeçalhos de resposta, use Shared-Storage-Write no cabeçalho de resposta para transmitir a chave a ser excluída.

  delete;key="myKey"
  

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

  clear;
  

Troca de contexto

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

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 bloco Cloud Storage. Quando você carrega o código de terceiros em um iframe, o código recebe um novo contexto de navegação, e sua origem é a origem do iframe. Portanto, a chamada sharedStorage.set() feita a partir 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 de adtech ou de terceiros ao criar um iframe e chamar set() ou delete() no código JavaScript da no iframe.

API Private Aggregation

Para medir os dados agregáveis armazenados no armazenamento compartilhado, use o API Aggregate.

Para criar um relatório, chame contributeToHistogram() dentro de um worklet com uma bucket e 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, criptografados em trânsito e só podem ser descriptografados e agregados usando Serviço de agregação.

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

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

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

Como usar iframe de origem cruzada

É necessário um iframe para invocar o worklet de armazenamento compartilhado.

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

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

No script do worklet, é preciso criar uma classe com uma run assíncrona. . E register para que essa classe seja executada no iframe do anúncio. 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);

Como usar solicitação de origem cruzada

O armazenamento compartilhado e a agregação privada permitem a criação de worklets de origem cruzada. sem a necessidade de iframes de origem cruzada.

A página própria pode invocar uma chamada createWorklet() para o namespace endpoint do JavaScript.

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

O endpoint JavaScript de origem cruzada precisará responder com os cabeçalhos. Shared-Storage-Cross-Origin-Worklet-Allowed e permitir origens cruzadas usando Access-Control-Allow-Origin.

Aviso: os cabeçalhos de resposta do script do worklet precisarão ativar essa opção com o CORS Access-Control-Allow-Origin e Shared-Storage-Cross-Origin-Worklet-Allowed. Tenha cuidado ao fornecer acesso ao seu worklet, pois não é o seu documento que está solicitando a sua worklet para execução.

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

Os Worklets criados usando createWorklet() terão selectURL e run(). addModule() não está disponível para isso.

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

Depuração

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

privateAggregation.enableDebugMode();

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

privateAggregation.enableDebugMode({debugKey: 1234});

Como depurar o armazenamento compartilhado

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

Promise is rejected without and explicit error message

Você pode depurar o armazenamento compartilhado unindo as chamadas com try-catch (link em inglês) blocos.

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. Relatórios de depuração recebem um payload semelhante a este JSON. Esse payload define o 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\"}"
}

Depurar payload de texto não criptografado

O debug_cleartext_payload é Base64 Codificada em CBOR. É possível conferir o bucket e valor usando o decoder ou use o código JavaScript encontrado no arquivo Armazenamento compartilhado decodificador.

Próximas etapas

As páginas a seguir explicam aspectos importantes das políticas de APIs de agregação.

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

Depois de se familiarizar com as APIs, você pode começar a coletar relatórios, que são enviados como uma solicitação POST para os seguintes pontos de extremidade 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, você poderá realizar testes usando o recurso de teste local ferramenta ou configure o ambiente de execução confiável para agregação Serviço para acessar os relatórios agregados.

Envie feedback

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

• Armazenamento compartilhado
• Agregação particular