Ofertas da API Protected Audience

Implementar transações, também conhecidas como marketplace privado (PMP, na sigla em inglês) em um leilão com Protected Audience

Visão geral

As transações, também chamadas de marketplace privado (PMP, na sigla em inglês), oferecem acesso a um conjunto de inventário ou preços preferenciais para os compradores. Para facilitar as transações programáticas, são usados códigos de licença e códigos de transação:

  • O ID da licença é um identificador que representa o cliente do comprador. Um ID de assento pode ter implicações de faturamento, por exemplo, se um assento tiver um desconto com um determinado vendedor.
  • O ID da transação tem origem no comprador ou no vendedor e é um identificador que representa um contrato entre um comprador e um vendedor. Um ID da transação pode ter propriedades, como custo/preço, compromisso de volume, informações de público-alvo, exclusividade e muito mais.

A API Protected Audience facilita as transações usando IDs de relatórios, que permitem a disponibilização de IDs de licenças e transações para lances, pontuações e relatórios de leilões. Esses IDs oferecem um mecanismo para que as empresas de adtech recebam esses IDs de oferta e de licenças nos relatórios da API Protected Audience pós-leilão para realizar transações e organizar iniciativas de faturamento. Esperamos que compradores, vendedores, agências e anunciantes tenham estratégias personalizadas para interpretar e entender os IDs das transações e das licenças que recebem.

Tutorial

Estas são as etapas para facilitar as transações em um leilão com Protected Audience:

  1. O comprador registra a transação e os IDs de assento na configuração do grupo de interesse antes da realização do leilão.
    • Os IDs de transações e licenças podem ser definidos no campo IDs de relatórios selecionáveis (selectableBuyerAndSellerReportingIds).
    • Se o ID da licença for o mesmo para todas as transações, ele poderá ser definido em buyerAndSellerReportingId, e os IDs da transação poderão ser definidos no campo de IDs de relatórios selecionáveis (selectableBuyerAndSellerReportingIds).
  2. Durante a geração de lances, os IDs da transação e da licença ficam disponíveis. O comprador seleciona um ID de transação de selectableBuyerAndSellerReportingIds. O comprador gera um lance que inclui um código da transação associado a esse lance retornando um selectedBuyerAndSellerReportingId. Um lance só pode vencer o leilão se o ID da transação retornado for k-anônimo junto com outros IDs de relatórios e propriedades selecionadas do grupo de interesse.
  3. Durante a classificação do anúncio, a transação e os IDs de assento selecionados ficam disponíveis para o vendedor.
  4. Os IDs da transação e da licença ficam disponíveis nas funções de relatórios do vendedor.
  5. Os IDs da transação e do assento ficam disponíveis nas funções de relatórios do comprador.
.

1. Registro de IDs de ofertas e licenças

O comprador registra a transação e os IDs de assento na configuração do grupo de interesse antes da realização do leilão. Os IDs da oferta e do assento são definidos em selectableBuyerAndSellerReportingIds como uma matriz de strings. Se o ID da licença for o mesmo para todas as transações e não precisar ser repetido, adicione-o ao campo buyerAndSellerReportingId, que aceita uma string:

const interestGroupConfig = {
  owner: 'https://buyer.example',
  name: 'example-ig',
  ad: [
    {
      renderURL: 'https://buyer.example/ad.html',
      selectableBuyerAndSellerReportingIds: ['deal123', 'deal456', 'deal789'], // Deal IDs
      buyerAndSellerReportingId: 'seat123', // Seat ID

      // Though it is not used to facilitate deals, the buyer
      // reporting ID can be defined with other reporting IDs
      buyerAndReportingId: 'brid123'
    },
  ],
};

navigator.joinAdInterestGroup(interestGroupConfig);

Se o ID da licença for diferente para as transações, será possível usar a seguinte configuração:

const interestGroupConfig = {
  owner: 'https://buyer.example',
  name: 'example-ig',
  ad: [
    {
      renderURL: 'https://buyer.example/ad.html',
      selectableBuyerAndSellerReportingIds: [
        'deal123seat123',
        'deal456seat456',
        'deal789seat456'
      ], // Deal and Seat IDs
    },
  ],
};

navigator.joinAdInterestGroup(interestGroupConfig);

2. IDs de transações e licenças para compradores durante a geração de lances

Durante a geração de lances, o comprador decide se quer dar lances em um ID da transação. Em generateBid(), o comprador pode selecionar um ID de transação em selectableBuyerAndSellerReportingIds e retornar o valor como selectedBuyerAndSellerReportingId. O lance vai ser rejeitado se o ID da transação selecionado não estiver na matriz selectableBuyerAndSellerReportingIds.

function generateBid(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'seat123'
    selectableBuyerAndSellerReportingIds // ['deal123', 'deal456', 'deal789']
    buyerAndReportingId // 'brid123' - Not used for deals, but the value is available
  } = browserSignals;

  // ...

  return {
    bid: 1,
    render: 'https://buyer.example/ad.html',
    selectedBuyerAndSellerReportingId: 'deal456', // Buyer selects a deal ID
  };
}

Um lance com um valor retornado para selectedbuyerAndSellerReportingId só poderá vencer o leilão se o valor de selectedbuyerAndSellerReportingId for conjuntamente k-anônimo com buyerAndSellerReportingId (se houver), buyerReportingId (se houver) o proprietário do grupo de interesse, o URL do script de lances, o URL de renderização e o tamanho do anúncio (o tamanho do anúncio será excluído dessa verificação até pelo menos o primeiro trimestre de 2025).

Mesmo que selectablebuyerAndSellerReportingIds esteja definido na configuração do grupo de interesse, ainda é válido que generateBid() retorne um lance que não inclua um selectedbuyerAndSellerReportingId. nesse caso, os IDs de relatórios fornecidos às funções de geração de relatórios se o lance vencer seguir o comportamento dos IDs de relatórios não selecionáveis.

Nos casos em que generateBid() é executado novamente porque a invocação inicial não produziu lances com anúncios que foram aprovados nas verificações de k-anonimato, selectableBuyerAndSellerReportingIds que não passarem na verificação de k-anonimato não vai estar presente no grupo de interesse na nova execução.

3. IDs de transação e assento para vendedores durante a pontuação do anúncio

O ID da transação selecionado e um ID da licença, se houver, ficam acessíveis para scoreAd(). O vendedor informa a pontuação de atratividade do lance vencedor considerando o ID da transação e os termos especiais. Se o vendedor não acreditar que o ID da transação escolhido pelo comprador se aplica, ele rejeitará o lance atribuindo a ele uma pontuação de desejabilidade zero ou negativa.

function scoreAd(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'seat123'
    selectedBuyerAndSellerReportingIds, // 'deal456'
  } = browserSignals;

  // ...
}

4. IDs de ofertas e licenças para relatórios de vendedores

Lembre-se de que um lance só poderá vencer o leilão se selectedBuyerAndSellerReportingId, buyerAndSellerReportingId (se houver) e buyerReportingId (se houver) forem k-anônimos com o proprietário do grupo de interesse, o URL do script de lances, o URL de renderização e o tamanho do anúncio (o tamanho do anúncio será excluído dessa verificação até pelo menos o primeiro trimestre de 2025). Dessa forma, os valores do ID de relatório que incluem um selectedBuyerAndSellerReportingId vão estar sempre disponíveis dentro de reportResult(). Embora buyerReportingId seja verificado quanto a k-anonimato, o valor só está disponível para a função de geração de relatórios do comprador, e não para a função de relatório do vendedor.

function reportResult(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'seat123'
    selectedBuyerAndSellerReportingIds // 'deal456'
  } = browserSignals;

  // ...
}

5. IDs de transações e licenças para relatórios de compradores

O mesmo conceito dos relatórios de vendedores se aplica aos relatórios de compradores. Lembre-se de que um lance só pode vencer o leilão se selectedBuyerAndSellerReportingId, buyerAndSellerReportingId (se presente) e buyerReportingId (se presente) forem k-anônimos com o proprietário do grupo de interesse, o URL do script de lance, o URL de renderização e o tamanho do anúncio (o tamanho do anúncio está excluído desta verificação até pelo menos o primeiro trimestre de 2025). Dessa forma, os valores do ID de relatórios que incluem um selectedBuyerAndSellerReportingId sempre estarão disponíveis dentro de reportWin().

function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'seat123'
    selectedBuyerAndSellerReportingId // 'deal456'
    buyerAndReportingId // 'brid123' - Not used for deals, but the value is available
  } = browserSignals;
}

Interaja e compartilhe feedback