Esta página foi traduzida pela API Cloud Translation.

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 privada. Você precisa entender as duas APIs, porque o Shared Storage armazena os valores e a Private Aggregation cria os relatórios agregáveis.

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

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. No entanto, há casos de uso em que o armazenamento não particionado é necessário. A API Shared Storage oferece acesso de gravação ilimitado a diferentes sites de nível superior com acesso de leitura que preserva a privacidade.

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

O armazenamento compartilhado tem um limite de capacidade por origem. Cada entrada tem 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 no explicador de armazenamento compartilhado.

Como invocar armazenamento compartilhado

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

Usar JavaScript: as adtechs podem executar funções específicas de armazenamento compartilhado, como definir, anexar e excluir valores fora de um 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 usando um worklet JavaScript. Os métodos que podem ser usados fora de um worklet do JavaScript podem ser encontrados em Proposed API Surface - Outside the worklet.

Os métodos usados no worklet durante uma operação podem ser encontrados em Proposed API Surface - In the worklet.
Como usar cabeçalhos de resposta

Assim como no JavaScript, somente 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 Shared Storage 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 abaixo, dependendo do 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>
```
- 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";
```

Confira mais informações 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 for chamado de fora do worklet, os dados serão gravados na origem do contexto de navegação em que a chamada foi feita. Se chamados 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 a partir da última atualização.

O campo ignoreIfPresent é opcional. Se estiver presente e definido como true, a chave não será atualizada se já existir. A validade 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 na mesma carga 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.

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

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írgulas e podem 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 usando o método de anexação. Se a chave não existir, a chamada append() vai criar a chave e definir o valor. Isso pode ser feito usando JavaScript ou cabeçalhos de resposta.

Usando JavaScript

Para atualizar os valores das chaves atuais, use sharedStorage.append() dentro ou fora do 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 do worklet:

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

Como usar cabeçalhos de resposta

Assim como ao definir um valor no Armazenamento compartilhado, você pode 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 ler 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.

Como excluir do armazenamento compartilhado

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

Usando JavaScript

Para excluir do armazenamento compartilhado de fora do worklet:
```
window.sharedStorage.delete('myKey');
```
Para excluir do armazenamento compartilhado dentro do worklet:
```
sharedStorage.delete('myKey');
```
Para excluir todas as chaves de uma só vez fora do worklet:
```
window.sharedStorage.clear();
```
Para excluir todas as chaves de uma vez dentro do worklet:
```
sharedStorage.clear();
```
Como usar cabeçalhos de resposta

Para excluir valores usando cabeçalhos de resposta, você também pode usar 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 Shared Storage são gravados na origem (por exemplo, https://example.adtech.com) do contexto de navegação de onde a chamada originou.

Quando você carrega o código de terceiros usando uma tag <script>, ele é 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 origem do iframe. Portanto, a chamada sharedStorage.set() feita pelo 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 chame sharedStorage.set() ou sharedStorage.delete(), o par de chave-valor será armazenado no contexto próprio.

Dados armazenados em uma página própria com JavaScript de terceiros incorporado.

Contexto de terceiros

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

Dados armazenados no contexto de adtech ou de terceiros.

API Private Aggregation

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

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 sem assinatura, 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 em 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 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 particular

Você precisa criar um worklet para acessar dados do armazenamento compartilhado. Para fazer isso, chame createWorklet() com o URL do worklet. Por padrão, ao usar o armazenamento compartilhado com createWorklet(), a origem da partição de dados será a origem do contexto de navegação de invocação, não a origem do próprio script do worklet.

Para mudar o comportamento padrão, defina a propriedade dataOrigin ao chamar createWorklet.

dataOrigin: "context-origin": (padrão) os dados são armazenados no armazenamento compartilhado da origem do contexto de navegação de invocação.
dataOrigin: "script-origin": os dados são armazenados no armazenamento compartilhado da origem do script do worklet. É necessário ativar o modo.

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

Para ativar, ao usar "script-origin", o endpoint do script precisará responder com o cabeçalho Shared-Storage-Cross-Origin-Worklet-Allowed. O CORS precisa estar ativado para solicitações entre origens.

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

Como usar iframes entre origens

Um iframe é necessário para invocar o worklet de armazenamento compartilhado.

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

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

No script do worklet, você precisa criar uma classe com um método run assíncrono e register para que ele seja executado 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,
      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 também pode invocar uma chamada createWorklet() para o endpoint de JavaScript entre origens. Ao criar o worklet, defina a origem da partição de dados do worklet como a mesma da origem do script.

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

O endpoint de JavaScript entre origens terá que responder com os cabeçalhos Shared-Storage-Cross-Origin-Worklet-Allowed e observar que o CORS está ativado para a solicitação.

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

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

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

Próximas etapas

As páginas a seguir explicam aspectos importantes das APIs Shared Storage e Private Aggregation.

Depois de conhecer as APIs, você pode começar a coletar os relatórios, que são enviados como uma solicitação POST para os endpoints a seguir 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á testar usando a ferramenta de teste local ou configurar o Ambiente de execução confiável para o serviço de agregação para receber os relatórios agregados.

Envie feedback

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