Quando um leilão da Protected Audience retorna um candidato a anúncio, ele pode ser
retornado como um URN opaco, usado para renderizar um anúncio em um iframe, ou um
FencedFrameConfig, que é usado para renderizar o anúncio em um frame isolado.
Neste guia, explicamos o que é um frame isolado e por que ele é necessário. Além disso, você verá como renderizar um anúncio usando qualquer um dos métodos. Para uma visão mais aprofundada sobre frames isolados, encontre mais informações neste guia ou na proposta.
O que são frames isolados?
Um frame isolado (<fencedframe>) é um elemento HTML para conteúdo incorporado,
semelhante a um iframe. Ao contrário de iframes, um frame isolado restringe a comunicação
com o contexto de incorporação para permitir que o frame acesse dados entre sites sem
compartilhá-los com o contexto de embedding. Da mesma forma, nenhum dado próprio no
contexto de incorporação não pode ser compartilhado com o frame isolado.
Por exemplo, digamos que news.example (o contexto de embedding) incorpore um anúncio de
shoes.example em um frame isolado. A news.example não pode exfiltrar dados do
anúncio shoes.example, e shoes.example não pode aprender dados próprios do
news.example.
Como os frames isolados funcionam?
Os frames delimitados usam o objeto FencedFrameConfig para navegação. Esse objeto pode
ser retornado de um leilão da Protected Audience. Em seguida, o objeto de configuração é definido como
o atributo config no elemento do frame isolado. Ele é diferente de um iframe,
em que um URL ou URN opaco é atribuído ao atributo src. O
objeto FencedFrameConfig tem uma propriedade url somente leitura. No entanto, como os
casos de uso atuais exigem que o URL real do recurso interno esteja oculto,
essa propriedade retorna a string opaca quando lida.
Um frame isolado não pode usar postMessage para se comunicar com o incorporador.
No entanto, um frame isolado pode usar postMessage com iframes dentro do
frame isolado.
Os frames delimitados serão isolados do editor de outras maneiras. O editor não terá acesso ao DOM dentro de um frame isolado, e o frame isolado não terá acesso ao DOM do editor. Além disso, atributos como name, que podem
ser definidos como qualquer valor e observado pelo editor, não estão disponíveis em frames
delimitados.
Os frames delimitados se comportam como um contexto de navegação de nível superior, como uma guia do
navegador. Ainda que um frame isolado em determinados casos de uso (como opaque-ads)
possa conter dados entre sites, como um grupo de interesse da API Protected Audience,
o frame não pode acessar cookies ou armazenamento não particionados. Um frame isolado
opaque-ads pode acessar um cookie e uma partição de armazenamento exclusivos e baseados em valor de uso único.
Confira mais detalhes sobre as características dos frames delimitados na explicação.
Renderizar um anúncio em um frame isolado
Uma FencedFrameConfig é retornada de um leilão da Protected Audience, desde que
o parâmetro resolveToConfig da AuctionConfig tenha sido definido como verdadeiro:
const frameConfig = await navigator.runAdAuction({
// ...auction configuration
resolveToConfig: true
});
Depois de receber a configuração, é possível atribuí-la ao atributo config de um frame isolado
para navegar pelo frame até o recurso representado pela configuração.
As versões anteriores do Chrome não são compatíveis com a propriedade resolveToConfig. Portanto, você ainda precisa confirmar que a promessa foi resolvida como um FencedFrameConfig antes de navegar:
if (window.FencedFrameConfig && frameConfig instanceof FencedFrameConfig) {
const frame = document.createElement('fencedframe');
frame.config = frameConfig;
}
Renderizar um anúncio em um iframe
Se AuctionConfig não definir resolveToConfig explicitamente ou se estiver definido
como falso, runAdAuction() retornará um URN opaco. Esse URN pode ser definido como um
src de iframe para renderizar o anúncio.