Ofertas da API Protected Audience

Implementar transações, também conhecidas como marketplace privado (PMP), em um leilão da API Protected Audience

Visão geral

As transações, também chamadas de marketplace privado (PMP), oferecem acesso selecionado ou preços preferenciais para compradores em um subconjunto de inventário. Para facilitar as transações programáticas, são usados IDs de assento e IDs de transação:

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

A Protected Audience facilita as transações usando IDs de relatórios, o que permite que os IDs de assento e de transação fiquem disponíveis para lances, pontuação e relatórios de leilão. Os IDs de relatórios oferecem um mecanismo para que as empresas de adtech recebam esses IDs de transação e licença em relatórios pós-leilão do Protected Audience para fazer transações e organizar as atividades de faturamento. Esperamos que compradores, vendedores, agências e anunciantes tenham estratégias personalizadas para interpretar e entender os IDs de transação e assento que recebem.

Tutorial

As etapas para facilitar as transações em um leilão da Protected Audience são as seguintes:

  1. O comprador registra os IDs da transação e da licença na configuração do grupo de interesse antes da execução do leilão.
    • Os IDs de transação e assento 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 das transações 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 carteira ficam disponíveis. O comprador seleciona um ID de transação em selectableBuyerAndSellerReportingIds. O comprador gera um lance que inclui um ID de transação associado a ele retornando um selectedBuyerAndSellerReportingId. Um lance só pode vencer o leilão se o ID do negócio retornado for k-anônimo com outros IDs de relatórios e propriedades selecionadas do grupo de interesse.
  3. Durante a pontuação do anúncio, a transação selecionada e os IDs de assento ficam disponíveis para o vendedor.
  4. Os IDs da transação e do assento 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 transação e licença

O comprador registra os IDs da transação e da licença na configuração do grupo de interesse antes da execução do leilão. Os IDs de transação e assento são definidos em selectableBuyerAndSellerReportingIds como uma matriz de strings. Se o ID do assento for o mesmo para todas as transações e não precisar ser repetido, ele poderá ser adicionado 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
      buyerReportingId: 'brid123'
    },
  ],
};

navigator.joinAdInterestGroup(interestGroupConfig);

Se o ID do assento for diferente para as ofertas, use 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ção e licença para compradores durante a geração de lances

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

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

  // ...

  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 k-anônimo em conjunto com buyerAndSellerReportingId (se presente), buyerReportingId (se presente), 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 relatórios se esse lance vencer vão seguir o comportamento de ID de relatório não selecionável.

Nos casos em que generateBid() é executado novamente porque a invocação inicial não gerou lances com anúncios que passaram nas verificações de k-anonimato, os selectableBuyerAndSellerReportingIds que não passam na verificação de k-anonimato não estarão presentes no grupo de interesse na nova execução.

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

O ID da transação selecionado, junto com um ID de licença por usuário, se presente, são disponibilizados para scoreAd(). O vendedor informa a pontuação de conveniência do lance vencedor considerando o ID da transação e quaisquer termos especiais. Se o vendedor não achar que o ID da transação escolhido pelo comprador é aplicável, ele vai 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 transação e licença para relatórios de vendedores

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 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). Assim, os valores de ID de relatórios que incluem um selectedBuyerAndSellerReportingId estarão sempre disponíveis em reportResult(). Embora buyerReportingId seja verificado para 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 geração de relatórios do vendedor.

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

  // ...
}

5. IDs de transação e de licença para relatórios do comprador

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 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). Assim, os valores de ID de relatórios que incluem um selectedBuyerAndSellerReportingId sempre estarão disponíveis em reportWin().

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

Interagir e compartilhar feedback