Renderizar um anúncio

Quando um leilão de público-alvo protegido 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, usado para renderizar o anúncio em um frame isolado.

Este guia explica o que é um frame isolado e por que ele é necessário, além de como renderizar um anúncio usando qualquer um dos métodos. Para mais detalhes sobre frames isolados, consulte este guia ou a 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 dos iframes, um frame isolado restringe a comunicação com o contexto de incorporação para permitir o acesso a dados entre sites sem compartilhá-los com o contexto de incorporação. Da mesma forma, nenhum dado próprio no contexto de incorporação pode ser compartilhado com o frame isolado.

Por exemplo, digamos que news.example (o contexto de incorporação) incorpore um anúncio de shoes.example em um frame isolado. news.example não pode exfiltrar dados do anúncio shoes.example, e shoes.example não pode aprender dados próprios de news.example.

Como os frames isolados funcionam?

Os frames isolados 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 de frame isolado. Isso é 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 seja ocultado, essa propriedade retorna a string "opaque" quando lida.

Um frame delimitado não pode usar postMessage para se comunicar com o incorporador. No entanto, um frame isolado pode usar postMessage com iframes dentro dele.

Os frames isolados também serão isolados do publisher de outras maneiras. O editor não terá acesso ao DOM dentro de um frame isolado, e o frame isolado não poderá acessar o DOM do editor. Além disso, atributos como name, que podem ser definidos como qualquer valor e observados pelo editor, não estão disponíveis em frames isolados.

Os frames isolados se comportam como um contexto de navegação de nível superior (como uma guia do navegador). Embora 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), ele não pode acessar armazenamento ou cookies não particionados. Um frame isolado opaque-ads pode acessar um cookie e uma partição de armazenamento exclusivos baseados em nonce.

As características dos frames isolados são detalhadas no explainer.

Renderizar um anúncio em um frame isolado

Um FencedFrameConfig é retornado de um leilão da Protected Audience, desde que o parâmetro resolveToConfig de AuctionConfigs tenha sido definido como verdadeiro:

const frameConfig = await navigator.runAdAuction({
  // ...auction configuration
  resolveToConfig: true
});

Depois de receber a configuração, atribua-a ao atributo config de um frame isolado para navegar até o recurso representado pela configuração. Versões anteriores do Chrome não são compatíveis com a propriedade resolveToConfig. Portanto, ainda é necessário confirmar se a promessa foi resolvida para 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 o AuctionConfig não definir explicitamente resolveToConfig ou se ele estiver definido como "false", runAdAuction() vai retornar um URN opaco. Esse URN pode ser definido como um iframe src para renderizar o anúncio.