O Chrome está deixando gradativamente o suporte a cookies de terceiros para reduzir o rastreamento entre sites. Isso representa um desafio para sites e serviços que dependem de cookies em contextos incorporados, para jornadas do usuário, como autenticação. A API Storage Access (SAA) permite que esses casos de uso continuem funcionando, limitando o máximo possível o rastreamento entre sites.
Status da implementação
A API Storage Access está disponível nos principais navegadores, mas há pequenas diferenças de implementação. Essas diferenças foram destacadas nas seções relevantes desta postagem.
Estamos trabalhando para resolver todos os problemas de bloqueio restantes antes de padronizar a API.
O que é a API Storage Access?
A API Storage Access é uma API JavaScript que permite que os iframes solicitem permissões de acesso ao armazenamento quando o acesso seria negado pelas configurações do navegador. Incorporações com casos de uso que dependem do carregamento de recursos entre sites podem usar a API para solicitar a permissão de acesso do usuário, conforme necessário.
Se a solicitação de armazenamento for concedida, o iframe terá acesso aos cookies entre sites, que também estão disponíveis quando os usuários o acessam como um site de nível superior.
A API Storage Access permite que um acesso específico a cookies entre sites seja fornecido com carga mínima para o usuário final e, ao mesmo tempo, impede o acesso genérico a cookies entre sites, já que é usada com frequência para rastreamento de usuários.
Casos de uso
Algumas incorporações de terceiros exigem acesso a cookies entre sites para oferecer uma experiência melhor ao usuário, algo que não estará disponível após o uso dos cookies de terceiros.
Os casos de uso incluem o seguinte:
- Widgets de comentários incorporados que exigem detalhes da sessão de login.
- Botões "Gostei" de mídias sociais, que precisam de detalhes da sessão de login
- Documentos incorporados que exigem detalhes da sessão de login.
- Uma experiência premium fornecida a um vídeo incorporado, por exemplo, para não exibir anúncios a usuários conectados, saber as preferências do usuário em relação a legendas ou restringir determinados tipos de vídeo.
- Sistemas de pagamento incorporados.
Muitos desses casos de uso envolvem a persistência de acesso por login em iframes incorporados.
Quando usar a API Storage Access em vez de outras APIs
A API Storage Access é uma das alternativas ao uso de cookies de terceiros. Por isso, é importante entender quando usar essa API em comparação com as outras. Ela é destinada a casos de uso em que ambos os casos a seguir são verdadeiros:
- O usuário vai interagir com o conteúdo incorporado, ou seja, não se trata de um iframe passivo ou oculto.
- O usuário visitou a origem incorporada em um contexto de nível superior, ou seja, quando ela não está incorporada em outro site.
Há APIs alternativas para diversos casos de uso:
- Os cookies com estado particionado independente (CHIPS, na sigla em inglês) permitem que os desenvolvedores ativem um cookie para o armazenamento "particionado", com um cookie jar separado por site de nível superior. Por exemplo, um widget de chat na Web de terceiros pode precisar da configuração de um cookie para salvar as informações da sessão. As informações da sessão são salvas por site. Assim, o cookie definido pelo widget não precisa ser acessado em outros sites onde também está incorporado. A API Storage Access é útil quando um widget incorporado de terceiros depende do compartilhamento das mesmas informações em origens diferentes, por exemplo, para preferências ou detalhes de sessões conectadas.
- Os conjuntos de sites relacionados (RWS, na sigla em inglês) são uma maneira de uma organização declarar relações entre sites para que os navegadores permitam acesso limitado a cookies de terceiros para fins específicos. Os sites ainda precisam solicitar acesso com a API Storage Access, mas, para sites dentro desse conjunto, o acesso pode ser concedido sem solicitações do usuário.
- O Federated Credential Management (FedCM) é uma abordagem que preserva a privacidade dos serviços de identidade federada. A API Storage Access lida com o acesso a cookies pós-login. Para alguns casos de uso, o FedCM fornece uma solução alternativa à API Storage Access, podendo ser preferível porque apresenta uma solicitação de navegador mais orientada por login. No entanto, a adoção do FedCM geralmente requer alterações adicionais no código, por exemplo, para oferecer suporte aos endpoints HTTP.
- Também existem APIs antifraude, relacionadas a anúncios e medição, e a API Storage Access não tem como objetivo resolver essas questões.
Como usar a API Storage Access
A API Storage Access tem dois métodos baseados em promessa:
Ele também se integra à API Permissions. Isso permite verificar o status da permissão de acesso ao armazenamento em um contexto de terceiros, que indica se uma chamada para document.requestStorageAccess() seria concedida automaticamente:
Como usar o método hasStorageAccess()
Quando um site é carregado pela primeira vez, ele pode usar o método hasStorageAccess() para verificar se o acesso a cookies de terceiros já foi concedido.
// Set a hasAccess boolean variable which defaults to false.
let hasAccess = false;
async function handleCookieAccessInit() {
if (!document.hasStorageAccess) {
// Storage Access API is not supported so best we can do is
// hope it's an older browser that doesn't block 3P cookies.
hasAccess = true;
} else {
// Check whether access has been granted via the Storage Access API.
// Note on page load this will always be false initially so we could be
// skipped in this example, but including for completeness for when this
// is not so obvious.
hasAccess = await document.hasStorageAccess();
if (!hasAccess) {
// Handle the lack of access (covered later)
}
}
if (hasAccess) {
// Use the cookies.
}
}
handleCookieAccessInit();
O acesso ao armazenamento só é concedido a um documento iframe depois que ele chama requestStorageAccess(),. Portanto, hasStorageAccess() sempre vai retornar "false" inicialmente, exceto quando outro documento de mesma origem no mesmo iframe já tiver recebido acesso. A concessão é preservada em navegações de mesma origem no iframe, especificamente para permitir atualizações após conceder acesso a páginas que exigem a presença de cookies na solicitação inicial do documento HTML.
Como usar o método requestStorageAccess()
Se o iframe não tiver acesso, talvez seja necessário solicitar acesso usando o método requestStorageAccess():
if (!hasAccess) {
try {
await document.requestStorageAccess();
} catch (err) {
// Access was not granted and it may be gated behind an interaction
return;
}
}
Na primeira vez que isso é solicitado, o usuário pode precisar aprovar o acesso com uma solicitação do navegador. Depois disso, a promessa será resolvida ou será rejeitada, resultando em uma exceção se await for usado.
Para evitar abusos, esta solicitação do navegador só será exibida após uma interação do usuário. É por isso que requestStorageAccess() inicialmente precisa ser chamado de um manipulador de eventos ativado pelo usuário, e não imediatamente durante o carregamento do iframe:
async function doClick() {
// Only do this extra check if access hasn't already been given
// based on the hasAccess variable.
if (!hasAccess) {
try {
await document.requestStorageAccess();
hasAccess = true; // Can assume this was true if above did not reject.
} catch (err) {
// Access was not granted.
return;
}
}
if (hasAccess) {
// Use the cookies
}
}
document.querySelector('#my-button').addEventListener('click', doClick);
Prompts de permissão
Quando o usuário clicar no botão pela primeira vez, a solicitação do navegador aparecerá automaticamente, geralmente na barra de endereço. Confira abaixo um exemplo de solicitação do Chrome, mas outros navegadores têm uma interface semelhante:
A solicitação pode ser ignorada pelo navegador, e a permissão é fornecida automaticamente em determinadas circunstâncias:
- Se a página e o iframe foram usados nos últimos 30 dias após a solicitação.
- Se o iframe incorporado fizer parte de um conjunto de sites relacionados.
- No Firefox, a solicitação também é ignorada para sites conhecidos (aqueles com os quais você interagiu no nível superior) nas cinco primeiras tentativas.
Como alternativa, o método pode ser rejeitado automaticamente sem exibir a solicitação em determinadas circunstâncias:
- Se o usuário não tiver visitado e interagido anteriormente com o site que possui o iframe como um documento de nível superior, não em um iframe. Isso significa que a API Storage Access só é útil para sites incorporados que os usuários já visitaram em um contexto próprio.
- Se o método
requestStorageAccess()for chamado fora de um evento de interação do usuário sem aprovação prévia da solicitação após uma interação.
Embora o usuário receba uma solicitação no uso inicial, as próximas visitas podem resolver o requestStorageAccess() sem aviso e sem exigir interação do usuário no Chrome e no Firefox. O Safari sempre exige uma interação do usuário.
Como o acesso a cookies pode ser concedido sem solicitação ou interação do usuário, muitas vezes é possível receber acesso a cookies de terceiros antes de uma interação do usuário em navegadores compatíveis com esse recurso (Chrome e Firefox), chamando requestStorageAccess() no carregamento da página. Isso permite que você acesse cookies de terceiros entre sites imediatamente e ofereça uma experiência mais completa, mesmo antes de o usuário interagir com o iframe. Em algumas situações, essa pode ser uma experiência do usuário melhor do que esperar pela interação do usuário.
Como usar a consulta de permissão storage-access
Para conferir se o acesso pode ser concedido sem uma interação do usuário, confira o status da permissão storage-access e só faça a chamada requestStoreAccess() antecipadamente se nenhuma ação do usuário for necessária, em vez de chamá-la e fazer com que ela falhe quando uma interação for necessária.
Isso também permite lidar com a necessidade de uma solicitação com antecedência ao exibir conteúdo diferente, como um botão de login.
O código a seguir adiciona a verificação de permissão storage-access ao exemplo anterior:
// Set a hasAccess boolean variable which defaults to false except for
// browsers which don't support the API - where we assume
// such browsers also don't block third-party cookies.
let hasAccess = false;
async function hasCookieAccess() {
// Check if Storage Access API is supported
if (!document.requestStorageAccess) {
// Storage Access API is not supported so best we can do is
// hope it's an older browser that doesn't block 3P cookies.
return true;
}
// Check if access has already been granted
if (await document.hasStorageAccess()) {
return true;
}
// Check the storage-access permission
// Wrap this in a try/catch for browsers that support the
// Storage Access API but not this permission check
// (e.g. Safari and older versions of Firefox).
let permission;
try {
permission = await navigator.permissions.query(
{name: 'storage-access'}
);
} catch (error) {
// storage-access permission not supported. Assume no cookie access.
return false;
}
if (permission) {
if (permission.state === 'granted') {
// Permission has previously been granted so can just call
// requestStorageAccess() without a user interaction and
// it will resolve automatically.
try {
await document.requestStorageAccess();
return true;
} catch (error) {
// This shouldn't really fail if access is granted, but return false
// if it does.
return false;
}
} else if (permission.state === 'prompt') {
// Need to call requestStorageAccess() after a user interaction
// (potentially with a prompt). Can't do anything further here,
// so handle this in the click handler.
return false;
} else if (permission.state === 'denied') {
// Currently not used. See:
// https://github.com/privacycg/storage-access/issues/149
return false;
}
}
// By default return false, though should really be caught by one of above.
return false;
}
async function handleCookieAccessInit() {
hasAccess = await hasCookieAccess();
if (hasAccess) {
// Use the cookies.
}
}
handleCookieAccessInit();
Iframes no modo sandbox
Ao usar a API Storage Access em iframes no modo sandbox, as seguintes permissões de sandbox são necessárias:
- O
allow-storage-access-by-user-activationé necessário para permitir o acesso à API Storage Access. - O
allow-scriptsé necessário para permitir o uso do JavaScript para chamar a API. - O
allow-same-originé necessário para permitir o acesso a cookies de mesma origem e outros tipos de armazenamento.
Exemplo:
<iframe sandbox="allow-storage-access-by-user-activation
allow-scripts
allow-same-origin"
src="..."></iframe>
Requisitos de cookies
Para serem acessados com a API Storage Access no Chrome, os cookies entre sites precisam ser definidos com estes dois atributos:
SameSite=None: obrigatório para marcar o cookie como entre sites.Secure: garante que somente os cookies definidos por sites HTTPS possam ser acessados.
No Firefox e no Safari, os cookies são padronizados como SameSite=None e não restringem o SSA a cookies Secure. Por isso, esses atributos não são obrigatórios. É recomendável deixar claro o atributo SameSite e sempre usar os cookies Secure.
Acesso à página de nível superior
A API Storage Access foi feita para permitir o acesso a cookies de terceiros em iframes incorporados.
Há também outros casos de uso em que a página de nível superior exige acesso a cookies de terceiros. Por exemplo, imagens ou scripts que são restritos por cookies, que os proprietários de sites podem querer incluir diretamente no documento de nível superior em vez de em um iframe. Para resolver esse caso de uso, o Chrome propôs uma extensão para a API Storage Access que adiciona um método requestStorageAccessFor().
Método requestStorageAccessFor()
O método requestStorageAccessFor() funciona de maneira semelhante ao requestStorageAccess(), mas para recursos de nível superior. Ele só pode ser usado em sites dentro de um conjunto de sites relacionados para evitar a concessão de acesso geral a cookies de terceiros.
Para mais detalhes sobre como usar o requestStorageAccessFor(), leia o conjunto de sites relacionados: guia para desenvolvedores.
A consulta de permissão top-level-storage-access
Compatibilidade com navegadores
- 119
- 119
- x
- x
Semelhante à permissão storage-access, há uma permissão top-level-storage-access para verificar se o acesso pode ser concedido para requestStorageAccessFor().
Qual é a diferença entre a API Storage Access quando usada com o RWS?
Quando os conjuntos de sites relacionados são usados com a API Storage Access, alguns outros recursos estão disponíveis, conforme detalhado na tabela a seguir:
| Sem RWS | Com RWS | |
|---|---|---|
| Requer um gesto do usuário para iniciar a solicitação de acesso ao armazenamento | ||
| Exige que o usuário visite a origem do armazenamento solicitada em um contexto de nível superior antes de conceder o acesso | ||
| O primeiro comando do usuário pode ser ignorado | ||
requestStorageAccess não vai precisar ser chamado se o acesso tiver sido concedido anteriormente |
||
| Concede automaticamente acesso a outros domínios em um site de site relacionado | ||
Compatível com requestStorageAccessFor o acesso à página de nível superior |
Demonstração: configuração e acesso a cookies
A demonstração a seguir mostra como um cookie definido por você na primeira tela da demonstração pode ser acessado em um frame incorporado no segundo site:
storage-access-api-demo.glitch.me
A demonstração requer um navegador com cookies de terceiros desativados:
- Chrome 118 ou versão mais recente com a sinalização
chrome://flags/#test-third-party-cookie-phaseoutdefinida e o navegador reiniciado. - Firefox
- Safari