Suporte para a segmentação por público-alvo personalizado usando a API Protected Audience

Enviar feedback

Atualizações recentes

A API Protected Audience está na versão Beta e está disponível para testes em dispositivos públicos.

Com a API Protected Audience, é possível:

  • Gerenciar públicos-alvo personalizados com base em ações anteriores do usuário.
  • Iniciar leilões no dispositivo com suporte para um único vendedor ou mediação em hierarquia.
  • Use os relatórios de impressão após a seleção de anúncios.

Para começar, leia o guia para desenvolvedores sobre a Protected Audience (link em inglês). Agradecemos seu feedback enquanto continuamos desenvolvendo a API Protected Audience.

Cronograma

Vamos lançar novos recursos nos próximos meses. As datas exatas de lançamento variam de acordo com o recurso e a tabela será atualizada com links para a documentação à medida que for disponibilizada.

Recurso Disponível na prévia para desenvolvedores Disponível na versão Beta
Relatórios de eventos 1º trimestre de 2023 3º trimestre de 2023
Mediação em hierarquia 1º trimestre de 2023 4º trimestre de 2023
Filtragem de anúncios de instalação de apps 2º trimestre de 2023 3º trimestre de 2023
Filtragem do limite de frequência 2º trimestre de 2023 3º trimestre de 2023
Transmitir anúncios contextuais ao fluxo de trabalho de seleção de anúncios para filtragem 2º trimestre de 2023 3º trimestre de 2023
Relatórios de interação 2º trimestre de 2023 3º trimestre de 2023
Participar da delegação de público-alvo personalizado 3º trimestre de 2023 4º trimestre de 2023
Faturamento sem CPM 3º trimestre de 2023 4º trimestre de 2023
Integração dos lances e serviços de leilão 3º trimestre de 2023 4º trimestre de 2023
Relatórios de depuração 3º trimestre de 2023 4º trimestre de 2023
Integração da Attribution Reporting N/A 4º trimestre de 2023
Mediação do Open Bidding 4º trimestre de 2023 4º trimestre de 2023
Gerenciamento de moedas 1º trimestre de 2024 2o trimestre de 2024
Integração com k-anonimato N/A 2o trimestre de 2024
Integração de relatórios agregados 3º trimestre de 2024 4o trimestre de 2024

Visão geral

Na publicidade para dispositivos móveis, os anunciantes procuram mostrar anúncios para usuários potencialmente interessados com base em interações anteriores com o app do anunciante. Por exemplo, o desenvolvedor do SportingGoodsApp pode querer mostrar um anúncio a usuários que tenham deixado itens no carrinho de compras como um lembrete para concluir a compra. Geralmente, o setor descreve essa ideia geral com termos como "remarketing" e "segmentação por público-alvo personalizado".

Atualmente, esses casos de uso são implementados ao compartilhar com plataformas de adtech as informações contextuais sobre como o anúncio é mostrado (por exemplo, o nome do app em que ele aparece) e informações particulares, como listas de público-alvo. Com essas informações, os anunciantes podem selecionar anúncios relevantes nos respectivos servidores.

A API Protected Audience no Android (anteriormente conhecida como FLEDGE) engloba as seguintes APIs para plataformas de adtech e anunciantes que oferecem suporte a casos de uso comuns com base em interação, o que limita o compartilhamento dos dois identificadores entre apps e as informações de interação de apps do usuário com terceiros:

  1. API Custom Audience: essa API é focada na abstração do "público-alvo personalizado", que representa um público-alvo com intenções comuns designado pelo anunciante. As informações do público-alvo ficam armazenadas no dispositivo e podem ser associadas a possíveis anúncios relevantes para esse público e a metadados arbitrários, como indicadores de lances. Essas informações podem ser usadas para orientar os lances do anunciante, a filtragem de anúncios e a renderização.
  2. API Ad Selection: oferece um framework para organizar os fluxos de trabalho das plataformas de adtech. Esses fluxos usam os indicadores do dispositivo para escolher um anúncio "vencedor", considerando anúncios candidatos armazenados localmente e realizando mais processamento dos anúncios candidatos que a plataforma retorna para o dispositivo.
Figura 1. Fluxograma que mostra o fluxo de trabalho para gerenciar um público-alvo personalizado e a escolha de anúncios no Sandbox de privacidade no Android.

De modo geral, a integração funciona desta maneira:

  1. O SportingGoodsApp quer lembrar os usuários de comprar itens deixados no carrinho de compras por mais de dois dias. O app usa a API Custom Audience para adicionar o usuário à lista de público-alvo com "produtos no carrinho". A plataforma gerencia e armazena essa lista de público-alvo no dispositivo, limitando o compartilhamento com terceiros. O SportingGoodsApp usa uma plataforma de adtech para veicular anúncios para usuários na lista de público-alvo. A plataforma, por sua vez, gerencia os metadados de listas de público-alvo e apresenta anúncios candidatos, que serão analisados pelo fluxo de trabalho de seleção de anúncios. A plataforma pode ser configurada para buscar periodicamente anúncios atualizados com base no público-alvo em segundo plano. Isso ajuda a manter a lista de anúncios candidatos atualizada com base no público-alvo e não correlacionada às solicitações enviadas a servidores de anúncios de terceiros durante a oportunidade de anúncio, ou seja, solicitações de anúncios contextuais.

  2. Ao jogar o FrisbeeGame no mesmo dispositivo, o usuário pode receber um anúncio com um lembrete para concluir a compra de itens deixados no carrinho de compras do SportingGoodsApp. Para fazer isso, o FrisbeeGame (com um SDK de anúncios integrado) invoca a API Ad Selection, que seleciona um anúncio vencedor para o usuário com base nas listas de público-alvo em que ele está. Neste exemplo, o público-alvo personalizado é "produtos no carrinho", criado pelo SportingGoodsApp. O fluxo de trabalho de seleção de anúncios pode ser configurado para considerar dois tipos de anúncios: aqueles extraídos dos servidores das plataformas e os encontrados no dispositivo, associados aos públicos-alvo personalizados e outros indicadores. O fluxo de trabalho também pode ser personalizado pela plataforma de adtech e pelo SDK de anúncios com lances personalizados e uma lógica de pontuação para atingir as metas de publicidade adequadas. Essa abordagem permite que os dados de interesses ou de interações com apps do usuário sejam usados para selecionar os anúncios, limitando o compartilhamento desses dados com terceiros.

  3. O SDK do app que veicula o anúncio ou da plataforma de adtech renderiza o anúncio selecionado.

  4. A plataforma facilita a geração de relatórios sobre resultados da seleção de anúncios e impressões. Esse recurso de geração de relatórios é complementar à API Attribution Reporting. As plataformas de adtech podem ser personalizadas de acordo com as necessidades de relatório.

Receber acesso ao público protegido nas APIs do Android

As plataformas de adtech precisam se registrar para acessar a API Protected Audience. Consulte Registrar uma conta do Sandbox de privacidade para mais informações.

Gerenciamento de público-alvo personalizado

Público-alvo personalizado

Um público-alvo personalizado representa um grupo de usuários, conforme determinado pelo anunciante, com intenções ou interesses comuns. Um SDK ou app pode especificar um público-alvo personalizado, por exemplo, alguém que "deixou itens no carrinho de compras" ou "concluiu os níveis para iniciantes" de um jogo. A plataforma mantém e armazena informações de público-alvo localmente no dispositivo. Além disso, ela não expõe a que públicos-alvo personalizados o usuário pertence. Os públicos-alvo personalizados são diferentes dos grupos de interesse do Chrome para públicos-alvo protegidos. Eles não podem ser compartilhados entre a Web e os apps. Isso ajuda a limitar o compartilhamento de informações do usuário.

Um app do anunciante ou o SDK integrado pode aderir ou sair de um público-alvo personalizado com base em informações como o engajamento do usuário em determinado app.

Metadados de público-alvo personalizado

Cada público-alvo personalizado contém os metadados abaixo:

  • Proprietário: nome do pacote do app proprietário. Isso é definido implicitamente como o nome do pacote do app autor da chamada.
  • Comprador: rede de publicidade do comprador, que gerencia anúncios para esse público-alvo personalizado. O comprador também representa as partes que podem acessar o público-alvo personalizado e buscar informações relevantes sobre anúncios. O comprador é especificado de acordo com o formato eTLD+1.
  • Nome: um nome ou identificador arbitrário para o público-alvo personalizado, como um usuário que "abandonou o carrinho de compras". Por exemplo, esse atributo pode ser usado como um dos critérios de segmentação nas campanhas de publicidade do anunciante ou como uma string de consulta no URL para buscar o código de lance.
  • Prazo de ativação e validade: esses campos definem o período pelo qual esse público-alvo personalizado vai permanecer válido. A plataforma usa essas informações para remover a associação a um público-alvo personalizado. O prazo de validade não pode exceder uma janela de duração máxima, para limitar a vida útil de um público-alvo personalizado.
  • URL de atualização diária: o URL usado pela plataforma para buscar anúncios candidatos e outros metadados definidos nos campos "Indicadores de lances do usuário" e "Indicadores de lances confiáveis" de maneira recorrente. Confira mais detalhes na seção sobre como buscar anúncios candidatos para públicos-alvo personalizados.
  • Indicadores de lances do usuário: indicadores específicos da plataforma de adtech para estabelecer lances de anúncios de remarketing. Exemplos de indicadores incluem a localização aproximada do usuário, a localidade de preferência, entre outros.
  • Dados de lances confiáveis: as plataformas de adtech contam com dados em tempo real para orientar o processo de escolha e pontuação dos anúncios. Por exemplo, um anúncio pode esgotar o orçamento definido e ter a veiculação interrompida imediatamente. Uma plataforma de adtech pode definir um endpoint do URL em que esses dados em tempo real podem ser buscados e o conjunto de chaves para as quais a pesquisa em tempo real precisa ser realizada. Essa solicitação será processada por um servidor confiável, gerenciado pela plataforma de adtech.
  • URL da lógica de lances: o URL usado pela plataforma para buscar o código de lances da plataforma de demanda. A plataforma realiza essa etapa quando um leilão de anúncios é iniciado.
  • Anúncios: uma lista de anúncios candidatos para o público-alvo personalizado. Isso inclui metadados de anúncios específicos da plataforma de adtech e um URL para renderizar o anúncio. Quando um leilão é iniciado para o público-alvo personalizado, essa lista de metadados do anúncio é considerada. A lista de anúncios vai ser atualizada usando o endpoint do URL de atualização diária, quando possível. Devido a restrições de recursos em dispositivos móveis, apenas um número limitado de anúncios pode ser armazenado para um público-alvo personalizado.

Delegação de público-alvo personalizado

A configuração e a definição tradicionais de público-alvo personalizado geralmente dependem de tecnologias e integrações do lado do servidor impulsionadas por adtechs em parceria com clientes e parceiros de agências e anunciantes. A API Protected Audience permite a definição e a configuração de público personalizado, protegendo a privacidade do usuário. Para participar de um público-alvo personalizado, as adtechs do comprador que não têm uma presença em relação a SDK em apps precisam colaborar com aquelas que têm uma presença em dispositivos, como parceiros de medição para dispositivos móveis (MMPs, na sigla em inglês) e plataformas de fornecimento (SSPs). O objetivo da API Protected Audience é oferecer suporte a esses SDKs, fornecendo soluções flexíveis para o gerenciamento de públicos-alvo personalizados, permitindo que os autores de chamadas no dispositivo invoquem a criação de públicos-alvo personalizados em nome dos compradores. Esse processo é chamado de delegação de público-alvo personalizado. Configure a delegação de público-alvo personalizado seguindo estas etapas:

Aderir a um público-alvo personalizado

Há duas maneiras de aderir a um público-alvo personalizado:

joinCustomAudience()

Um app ou SDK pode solicitar a adesão a um público-alvo personalizado chamando o método joinCustomAudience() após instanciar o objeto CustomAudience com os parâmetros esperados. Confira um exemplo de snippet de código ilustrativo:

CustomAudience audience = new CustomAudience(
    Buyer = "example-dsp.com",
    Name = "running-shoes",
    ActivationTime = now(),
    ExpirationTime = ActivationTime.plus(30 days),
    DailyUpdateURL = Uri.parse("https://..."),
    UserBiddingSignals = new JSONObject("{...}"),
    TrustedBiddingURL = Uri.parse("https://..."),
    TrustedBiddingKeys = {'key1","key2", ...,"key n"},
    BiddingLogicURL =  Uri.parse("https://..."),
    Ads = [new AdData(renderUrl = Uri.parse("https://..."),
           metadata = new JSONObject("{...}"), ...];

// Invoke ad services API to join a custom audience.
joinCustomAudience(audience);

fetchAndJoinCustomAudience()

Um app ou SDK pode solicitar a adesão a um público-alvo personalizado em nome de uma adtech que não tem uma presença no dispositivo, chamando fetchAndJoinCustomAudience() com os parâmetros esperados, como no exemplo abaixo:

FetchAndJoinCustomAudienceRequest fetchRequest = new FetchAndJoinCustomAudienceRequest(
    // Example: Optional verification token passed inside the fetch URL
    FetchURI = Uri.parse("https://example-dsp.com/...?mytoken=arbitrary1234"),
    // All the following parameters are optional
    Name = "running-shoes",
    ActivationTime = now(),
    ExpirationTime = ActivationTime.plus(30 days),
    UserBiddingSignals = new JSONObject("{...}")
);

fetchAndJoinCustomAudience(fetchRequest);

O endpoint do URL, de propriedade do comprador, responde com um objeto JSON CustomAudience no corpo da resposta. Os campos de comprador e proprietário do público-alvo personalizado são ignorados e preenchidos automaticamente pela API. Além disso, a API impõe que o URL de atualização diária também corresponda ao eTLD+1 do comprador.

{
 "name": "running-shoes",
 "activation_time": 1680603133000,
 "expiration_time": 1680803133000,
 "user_bidding_signals" : {"signal1": "value"},
 "trusted_bidding_data": {
    "trusted_bidding_uri": "https://example-dsp.com/.."
    "trusted_bidding_keys": ["k1", "k2"],
 },
 "bidding_logic_uri": "https://example-dsp.com/...",
 "daily_update_uri": "https://example-dsp.com/...",
 "ads": [
   {
     "render_uri": "https://example-dsp.com/...",
     "metadata": {},
     "ad_filters": {
       "frequency_cap": {
         "win": [
           {
             "ad_counter_key": 1,
             "max_count": 2,
             "interval_in_seconds": 60
           },
         ],
         "view": [
           {
             "ad_counter_key": 2,
             "max_count": 10,
             "interval_in_seconds": 3600
           },
         ]
       },
       "app_install": {
         "package_names": [
           "package.name.one",
           "package.name.two", ...
         ]
       }
     }
   },
   ...
 ]
}

A API fetchAndJoinCustomAudience() determina a identidade do comprador usando o eTLD+1 de fetchUri. A identidade do comprador CustomAudience é usada para executar as mesmas verificações de autorização e registro de app feitas por joinCustomAudience(). Essa ação não pode ser modificada pela resposta de busca. O proprietário de CustomAudience é o nome do pacote do aplicativo que fez a chamada. Não há outra validação de fetchUri além da verificação do eTLD+1 e, especificamente, não há verificação de k-anonimato. A API fetchAndJoinCustomAudience() emite uma solicitação HTTP GET para fetchUri e espera um objeto JSON que represente o público-alvo personalizado. Os mesmos valores obrigatórios e opcionais e os valores padrão dos campos de objeto de público-alvo personalizado são aplicados à resposta. Saiba mais sobre os requisitos e as limitações atuais no nosso guia para desenvolvedores.

Toda resposta de erro HTTP do comprador faz com que o fetchAndJoinCustomAudience falhe. Especificamente, uma resposta de status HTTP 429 (solicitações em excesso) bloqueia solicitações do aplicativo atual por um período a ser definido. A chamada de API também vai falhar se a resposta do comprador estiver incorreta. As falhas são relatadas ao autor da chamada da API responsável por tentar novamente devido a falhas temporárias (como o servidor não responder) ou tratar falhas persistentes (como falhas de validação de dados ou outros erros não transitórios com comunicação para o servidor).

O objeto CustomAudienceFetchRequest permite que o autor da chamada de API defina algumas informações para o público-alvo personalizado usando as propriedades opcionais mostradas no exemplo acima. Se definidos na solicitação, esses valores não podem ser substituídos pela resposta do comprador recebida pela plataforma. A API Protected Audience ignora os campos na resposta. Se não estiverem definidos na solicitação, eles precisarão ser definidos na resposta, porque esses campos são obrigatórios para criar um público-alvo personalizado. Uma representação JSON do conteúdo de CustomAudience, conforme parcialmente definido pelo autor da chamada de API, está incluída na solicitação GET para fetchUri em um cabeçalho especial X-CUSTOM-AUDIENCE-DATA. O tamanho da forma serializada dos dados especificados para o público-alvo personalizado é limitado a 8 KB. Se o tamanho for excedido, a chamada de API fetchAndJoinCustomAudience vai falhar.

Como não há uma verificação de k-anonimato, é possível usar fetchUri para a verificação do comprador e ativar o compartilhamento de informações entre o comprador e o SDK. Para facilitar a verificação de público-alvo personalizado, o comprador pode fornecer um token de verificação. O SDK no dispositivo precisa incluir esse token em fetchUri para que o endpoint hospedado pelo comprador possa buscar o conteúdo do público-alvo personalizado e usar o token de verificação para checar se a operação fetchAndJoinCustomAudience() corresponde ao comprador e se a origem é de um parceiro confiável no dispositivo. Para compartilhar informações, o comprador pode concordar com o autor da chamada no dispositivo para que algumas informações usadas para criar o público-alvo personalizado sejam adicionadas como parâmetros de consulta ao fetchUri. Isso permite que o comprador audite as chamadas e detecte se um token de validação foi usado por uma adtech maliciosa para criar diferentes públicos-alvo personalizados.

Observação sobre armazenamento e definição do token de verificação

  • O token de verificação não é usado pela API Protected Audience e é opcional.

    • O token de verificação pode ser usado pelo comprador para checar se os públicos-alvo estão sendo criados em nome dele.
    • A proposta da API Protected Audience não especifica um formato para o token de verificação nem como o comprador transfere o token para o autor da chamada. Por exemplo, o token de verificação pode ser pré-carregado no SDK ou no back-end do proprietário ou extraído em tempo real pelo SDK do proprietário no servidor do comprador.

Sair de um público-alvo personalizado

O proprietário de um público-alvo personalizado pode sair desse grupo. Para isso, é necessário chamar o método leaveCustomAudience(), conforme mostrado no snippet de código ilustrativo abaixo:

// Invoke ad services API to leave a custom audience.
leaveCustomAudience(buyer, name);

Para reduzir o uso do armazenamento e de outros recursos do dispositivo, os públicos-alvo personalizados expiram e são removidos do dispositivo após um período predeterminado. O valor padrão precisa ser determinado. Esse valor pode ser modificado pelo proprietário.

Controle do usuário

  • A proposta tem o objetivo de proporcionar aos usuários acesso à lista de apps instalados que criaram pelo menos um público-alvo personalizado.
  • Os usuários podem remover apps dessa lista. Após a remoção, todos os públicos-alvo personalizados associados ao app são excluídos, e o app não pode ser incluído em novos grupos.
  • Os usuários podem redefinir a API Protected Audience completamente. Quando isso acontece, todos os públicos-alvo personalizados no dispositivo são excluídos.
  • Os usuários podem recusar completamente o Sandbox de privacidade no Android, o que inclui a API Protected Audience. Se o usuário fizer isso, a API Protected Audience vai falhar silenciosamente.

A elaboração desse recurso está em andamento. Mais detalhes serão incluídos em uma atualização futura.

Permissões e controle do app

A proposta tem como objetivo permitir que os apps controlem os públicos-alvo personalizados:

  • Os apps podem gerenciar as associações realizadas com públicos-alvo personalizados.
  • Os apps podem conceder permissões a adtechs de terceiros para gerenciar públicos-alvo personalizados em nome do app.

A elaboração desse recurso está em andamento. Mais detalhes serão incluídos em uma atualização futura.

Controle da plataforma de adtech

Esta proposta descreve maneiras que as adtechs podem usar para controlar públicos-alvo personalizados:

  • As adtechs se inscrevem no Sandbox de privacidade e fornecem um domínio eTLD+1 que corresponde a todos os URLs de um público-alvo personalizado.
  • As adtechs podem fazer parcerias com apps ou SDKs para fornecer tokens de verificação usados para checar a criação de um público-alvo personalizado. Quando esse processo é delegado a um parceiro, a criação de públicos-alvo personalizados pode ser configurada para exigir o reconhecimento da adtech.
  • Uma adtech pode desativar as chamadas de joinCustomAudience em nome delas e permitir que a API fetchAndJoinCustomAudience ative todas as chamadas de públicos-alvo personalizados. O controle pode ser atualizado durante o registro no Sandbox de privacidade. O controle permite todas as adtechs ou nenhuma delas. Devido a limitações da plataforma, as permissões de delegação não podem ser feitas para cada adtech específica.

Resposta de metadados e anúncios candidatos

Os anúncios candidatos e os metadados retornados de uma plataforma de compra precisam incluir os campos abaixo:

  • Metadados: metadados de anúncios para compra específicos de tecnologias de publicidade. Por exemplo, isso pode incluir informações sobre a campanha publicitária e critérios de segmentação, como local e idioma.
  • URL de renderização: o endpoint para renderizar o criativo do anúncio.
  • Filtro: informações opcionais necessárias para que a API Protected Audience filtre anúncios com base nos dados do dispositivo. Para mais detalhes, leia a seção sobre lógica de filtragem de compras.

Fluxo de trabalho de seleção de anúncios

O objetivo desta proposta é melhorar a privacidade com a introdução da API Ad Selection, que organiza a execução de leilões para plataformas de adtech.

Atualmente, as plataformas de adtech costumam realizar processos de lance e seleção de anúncios exclusivamente em servidores próprios. Com essa proposta, os públicos-alvo personalizados e outros indicadores sensíveis de comportamento do usuário, como informações de pacotes instalados disponíveis, só poderão ser acessados usando a API Ad Selection. Além disso, para o caso de uso de remarketing, os anúncios candidatos serão buscados fora da banda, ou seja, fora do contexto em que são mostrados. As plataformas de adtech vão precisar se preparar para que partes da lógica atual de leilão e seleção de anúncios sejam implantadas e executadas no dispositivo. Essas plataformas podem estudar estas mudanças no fluxo de trabalho de seleção de anúncios:

  • Quando as informações sobre os pacotes instalados não estiverem disponíveis no servidor, as plataformas de adtech poderão enviar vários anúncios contextuais ao dispositivo e invocar o fluxo de trabalho de seleção de anúncios para ativar o filtro com base na instalação de apps e maximizar as chances de mostrar um anúncio relevante.
  • Como os anúncios de remarketing são buscados fora da banda, pode ser necessário atualizar os modelos de lances atuais. As plataformas de adtech podem criar submodelos de lances, que têm uma implementação baseada em um padrão conhecido como modelo de duas torres (link em inglês), que funcionam em recursos de anúncios e indicadores de contexto separadamente e combinam os resultados no dispositivo para prever lances. Esse processo se beneficia dos leilões do lado do servidor e dos leilões para qualquer oportunidade de anúncio.

Essa abordagem permite que os dados de interações no app do usuário sejam usados para selecionar anúncios e limita o compartilhamento desses dados com terceiros.

Figura 2. Fluxograma que mostra a iniciação do fluxo de trabalho de seleção de anúncios.

Esse fluxo de trabalho de seleção de anúncios organiza a execução no dispositivo do código JavaScript fornecido pelas tecnologias de publicidade com base nesta sequência:

  1. Execução da lógica de lances da compra
  2. Filtragem e processamento de anúncios de compra
  3. Execução de lógica de decisão da venda

Para seleções de anúncios que envolvem públicos personalizados, a plataforma vai buscar o código JavaScript de compra com base no endpoint do URL público definido pelos metadados "URL da lógica de lances" do público-alvo personalizado. O endpoint do URL para o código de decisão da venda também vai ser transmitido como uma entrada para iniciar o fluxo de trabalho de seleção de anúncios.

O modelo de seleções de anúncios que não envolvem públicos-alvo personalizados está em fase de desenvolvimento.

Iniciar o fluxo de trabalho da seleção de anúncios

Quando um app precisa mostrar um anúncio, o SDK da plataforma de adtech pode iniciar o fluxo de trabalho de seleção de anúncios chamando o método selectAds() depois de instanciar o objeto AdSelectionConfig com os parâmetros esperados:

  • Vendedor: identificador da plataforma de venda de anúncios, seguindo o formato eTLD+1.
  • URL da lógica de decisão: quando um leilão de anúncios é iniciado, a plataforma usa esse URL para buscar o código JavaScript da plataforma de venda e escolher um anúncio vencedor.
  • Compradores de públicos-alvo personalizados: uma lista de plataformas de compra que têm como demanda o público personalizado para o leilão. Ela segue o formato eTLD+1.
  • Indicadores de seleção de anúncios: informações sobre o leilão (tamanho e formato do anúncio, entre outros).
  • Indicadores do vendedor: indicadores específicos da plataforma de fornecimento.
  • URL de indicadores de pontuação confiáveis: o URL do endpoint dos indicadores confiáveis da plataforma de venda, em que é possível buscar informações específicas sobre o criativo, em tempo real.
  • Indicadores por comprador: os lados participantes podem usar esse parâmetro para fornecer informações sobre o leilão. Por exemplo, esse parâmetro pode incluir informações contextuais abrangentes que são úteis para determinar os lances.

O snippet de código ilustrativo abaixo mostra um SDK da plataforma de adtech que inicia o fluxo de trabalho de seleção de anúncios definindo primeiro a AdSelectionConfig e depois invocando selectAds para receber o anúncio vencedor:

AdSelectionConfig myAdSelectionConfig = new AdSelectionConfig {
    Seller = "example-ssp1.com",
    DecisionLogicURL = Uri.parse("https://..."),
    CustomAudienceBuyerList = Arrays.asList("example-dsp1.com","bexample-dsp2.com"),
    AdSelectionSignals = "{"min_price": 10,"auction_attempts": 3}"
    SellerSignals = "{"seller_type": "news", "content_category": "sports","mature_ads_accepted" :"false"}"
    PerBuyerSignals = " {"buyer1Name": {"key1" : "value1"},
                         "buyer2Name": {"key1" : "value1", "key2" : "value2" }"
};

// Invoke ad services API to initiate ad selection workflow.
Ad winningAd = selectAds(myAdSelectionConfig);

Lógica de lances de compra

A lógica de lances normalmente é fornecida pelas plataformas de compra. O objetivo do código é determinar os lances que são feitos para anúncios candidatos. Ele pode aplicar outra lógica de negócios para determinar esse resultado.

A plataforma usa os metadados do "URL da lógica de lances" do público-alvo personalizado para buscar o código JavaScript, que precisa incluir a assinatura de função abaixo:

generateBid(ad, auction_signals, per_buyer_signals, trusted_bidding_signals,
        contextual_signals, user_signals, custom_audience_signals) {
    // ...
    return {'bid': ...};
}

O método generateBid() retorna o valor do lance calculado. A plataforma invoca essa função para todos os anúncios, contextuais ou de remarketing, em sequência. Caso haja vários provedores de lógica de lances, o sistema não vai poder garantir a sequência de execução desses provedores.

A função espera receber os parâmetros abaixo:

  • Anúncio: o anúncio considerado pelo código do lance da plataforma de compra. Ele vai ser um anúncio de um público-alvo personalizado qualificado.
  • Indicadores de leilão: indicadores específicos da plataforma de venda.
  • Indicadores por comprador: os lados participantes podem usar esse parâmetro para fornecer informações sobre o leilão. Por exemplo, esse parâmetro pode incluir informações contextuais abrangentes que são úteis para determinar os lances.
  • Indicadores de lances confiáveis: as plataformas de tecnologias de publicidade contam com dados em tempo real para orientar o processo de escolha e pontuação dos anúncios. Por exemplo, uma campanha publicitária pode esgotar o orçamento definido e ter a veiculação dos anúncios interrompida imediatamente. Uma plataforma de tecnologias de publicidade pode definir um endpoint do URL em que esses dados em tempo real podem ser buscados e o conjunto de chaves para as quais a pesquisa em tempo real precisa ser realizada. O servidor gerenciado da plataforma de adtech que atender a essa solicitação passará a ser um servidor confiável gerenciado pela plataforma.
  • Indicadores contextuais: podem incluir carimbo de data/hora aproximado ou informações de localização aproximada ou custo por clique no anúncio.
  • Indicadores do usuário: podem incluir informações disponíveis, como o pacote instalado.

Custo do anúncio

Além do lance, as plataformas de compra têm a opção de retornar o custo por clique como parte de generateBid(). Por exemplo:

generateBid(ad, auction_signals, per_buyer_signals, trusted_bidding_signals,
        contextual_signals, user_signals, custom_audience_signals) {
    // ...
    return {'bid': ..., 'adCost': ...,};
}

Se este anúncio for o vencedor, adCost é arredondado estocasticamente para 8 bits por questões de privacidade. O valor arredondado de adCost é transmitido para o parâmetro contextual_signals em reportWin durante o relatório de impressões.

Lógica de filtragem da compra

As plataformas de compra vão poder filtrar anúncios com base em outros indicadores no dispositivo, que ficam disponíveis durante a fase de seleção de anúncios. Por exemplo, as plataformas de adtech podem implementar recursos de limite de frequência nesse momento. Quando há vários provedores de lógica de filtragem, o sistema garante a sequência de execução desses provedores.

A lógica de filtragem da compra pode ser implementada como parte da lógica de lances e retornar um valor de lance 0 para um determinado anúncio.

Além disso, as plataformas de compra vão poder indicar que um determinado anúncio precisa ser filtrado de acordo com outros indicadores no dispositivo, que estão disponíveis para a Protected Audience e não saem do dispositivo. À medida que solidificamos os projetos da lógica de filtragem extra, as plataformas de compra vão passar a seguir essa mesma estrutura para indicar que a filtragem é necessária.

Lógica de pontuação de venda

A lógica de pontuação geralmente é apresentada pela plataforma de venda. O objetivo do código é definir um anúncio vencedor com base nos resultados da lógica de lances. Ele pode aplicar outra lógica de negócios para determinar o resultado. Caso haja vários provedores de lógica de decisão, o sistema não vai poder garantir a sequência de execução desses provedores. A plataforma usa o parâmetro de entrada "URL da lógica de decisão" da API selectAds() para buscar o código JavaScript, que precisa incluir a assinatura de função abaixo:

scoreAd(ad, bid, auction_config, trusted_scoring_signals,
        contextual_signals, user_signals, custom_audience_signals) {
    // ...
    return score_for_this_ad;
}

A função espera receber os parâmetros abaixo:

  • Anúncio: o anúncio que está sendo avaliado, resultante da função generateBid().
  • Lance: valor do lance resultante da função generateBid().
  • Configuração do leilão: parâmetro de entrada para o método selectAds().
  • Indicadores de pontuação confiáveis: as plataformas de tecnologias de publicidade contam com dados em tempo real para orientar o processo de filtragem e pontuação de anúncios. Por exemplo, o editor de um app pode bloquear a exibição de anúncios de uma campanha publicitária no respectivo app. Para isso, o app busca dados do parâmetro de URL dos indicadores de pontuação confiáveis da configuração do leilão. O servidor que atende a essa solicitação precisa ser confiável e gerenciado por uma plataforma de adtech.
  • Indicadores contextuais: podem incluir o carimbo de data/hora aproximadas ou informações do local aproximado.
  • Indicador do usuário: pode incluir informações como a app store que iniciou a instalação do app.
  • Indicador de público-alvo personalizado: se o anúncio que está sendo pontuado for originado de um público-alvo personalizado gerado no dispositivo, o anúncio vai incluir informações como o leitor e o nome do público alvo personalizado.

Tempo de execução do código de seleção de anúncios

Na proposta, o sistema vai buscar o código de leilão fornecido pela plataforma de adtech em endpoints de URL configuráveis e executar esse código no dispositivo. Devido às restrições de recursos em dispositivos móveis, o código do leilão precisa seguir estas diretrizes:

  • A execução do código precisa ser concluída em um período previamente definido. Esse limite vai ser aplicado de maneira uniforme a todas as redes de publicidade do comprador. Os detalhes sobre esse limite vão ser compartilhados em uma atualização futura.
  • O código precisa ser autônomo e não ter dependências externas.

Já que o código do leilão, assim como a lógica de lances, pode precisar acessar dados particulares do usuário, como fontes de instalação de apps, o ambiente de execução não fornece acesso à rede ou ao armazenamento.

Linguagem de programação

O código do leilão fornecido pela plataforma de tecnologias de publicidade precisa ser programado em JavaScript. Isso permite que as plataformas de adtech compartilhem códigos de lances entre plataformas com suporte ao Sandbox de privacidade, por exemplo.

Renderização de anúncios vencedores

O anúncio com a maior pontuação é considerado o vencedor do leilão. Nesta proposta inicial, o anúncio vencedor é transmitido ao SDK para renderização.

O objetivo é ampliar essa solução para garantir que o app e o SDK não consigam usar as informações sobre o anúncio vencedor para descobrir se um usuário faz parte de determinado público-alvo personalizado ou descobrir o histórico de engajamento com apps do usuário, de modo semelhante à proposta de frames isolados (link em inglês) do Chrome.

Relatórios de impressões e eventos

Depois que o anúncio for renderizado, a impressão vencedora poderá ser informada às plataformas de compra e venda participantes. Isso permite que compradores e vendedores incluam informações do leilão, como o lance ou o nome do público-alvo personalizado, no relatório de impressões vencedoras. Além disso, as plataformas de venda e de compra são qualificadas para receber relatórios de evento sobre o anúncio vencedor. Assim, é possível incluir informações sobre o leilão (lance, nome do público-alvo personalizado e mais) com cliques, visualizações e outras interações com anúncios. A plataforma invoca a lógica de relatórios nesta ordem:

  1. Relatórios de venda.
  2. Relatórios de compra.

Isso oferece às plataformas de compra e venda uma maneira de enviar informações importantes contidas no dispositivo aos servidores para ativar recursos como orçamento em tempo real, atualizações do modelo de lances e fluxos de trabalho de faturamento precisos. Esse suporte oferecido para geração de relatórios de impressão é complementar à API Attribution Reporting.

Há duas etapas necessárias para oferecer suporte a relatórios de eventos: o JavaScript de venda e de compra precisa registrar para qual evento ele receberá relatórios, e o lado de venda é responsável por relatar informações no nível do evento.

O público-alvo protegido fornece um mecanismo para se inscrever em eventos futuros relacionados a um leilão vencedor, registrando beacons. Na função JavaScript reportResult() de um vendedor, as plataformas de venda podem registrar beacons usando a função registerAdBeacon() da plataforma. Da mesma forma, as plataformas de compra podem chamar o método registerAdBeacon() da função JavaScript reportWin().

registerAdBeacon(beacons)

Entrada:

  • event_key: uma string que indica para que tipo de interação o registro será feito. É usada como chave para pesquisar o ponto final dos pings da plataforma para informar os resultados do leilão.
  • reporting_url: é o URL da plataforma de adtech que processa o evento.

As chaves de interação são identificadores de string que pertencem ao SDK do vendedor responsável por informar os resultados do leilão. Para que um callback seja feito, as adtechs registram beacons com chaves que correspondem às chaves usadas pelo vendedor ao registrar os eventos. Eles não precisam ser k-anônimos, embora haja limites para a quantidade e o comprimento de chaves que podem ser registradas para um público-alvo personalizado. Se reportEvent() for chamado, as plataformas de venda que realizaram o leilão estarão sempre qualificadas para receber esses relatórios de eventos. Somente a plataforma vencedora do comprador está qualificada para receber esses relatórios.

Relatórios de venda

A plataforma invoca a função JavaScript reportResult() no código informado pela plataforma de fornecimento que foi transferido por download do parâmetro do URL da lógica de decisão do vendedor para a API selectAds():

reportResult(render_url, bid, auction_config, contextual_signals) {
    // ...
    beacons = {"click":clickUri}
    registerAdBeacon(beacons)
    return {
      "status": 0,
      "results": {"reporting_url": reporting_url,
                  "signals_for_buyer": signals_for_buyer}};
}

Saída: um objeto JSON contendo

  • Status: 0 para sucesso e qualquer outro valor para falha.
  • URL do relatório: a plataforma invoca esse URL retornado da função.
  • Indicadores para o comprador: um objeto JSON a ser transmitido para a função reportWin do comprador.

A plataforma de fornecimento pode codificar os indicadores relevantes no URL do relatório para os ajudar a ter mais informações sobre o leilão e o anúncio vencedor. Por exemplo, ela pode incluir os indicadores abaixo:

  • URL de renderização do anúncio
  • Valor do lance vencedor
  • Nome do app
  • Identificadores de consulta
  • Indicadores para o comprador: para oferecer suporte ao compartilhamento de dados entre o fornecimento e a demanda, a plataforma vai transmitir esse valor de retorno como um parâmetro de entrada ao código de relatório da demanda.

Relatórios de compra

A plataforma vai invocar a função JavaScript reportWin() no código informado pela demanda que foi transferido por download dos metadados do URL da lógica de lances do público-alvo personalizado associado ao leilão.

reportWin(render_url, bid, auction_signals, per_buyer_signals,
        signals_for_buyer, contextual_signals, custom_audience_signals) {
    // ...
    beacons = {"click":clickUri}
    registerAdBeacon(beacons)
    return {
      "status": 0,
      "results": {"reporting_uri": reporting_uri}};
}

Entrada:

  • auction_signals e per_buyer_signals são buscados em AuctionConfig. Qualquer informação que a plataforma de compra precise transmitir ao URL de relatório pode ser proveniente desse dado.
  • signals_for_buyer é o resultado de reportResult da plataforma de venda. Isso proporciona à plataforma de venda a oportunidade de compartilhar dados com a plataforma de compra para fins de geração de relatórios.
  • contextual_signals contém informações como o nome do app, enquanto custom_audience_signals contém as informações do público-alvo personalizado. Outras informações podem ser adicionadas no futuro.

Resultado:

  • Status: 0 para sucesso e qualquer outro valor para falha.
  • URL do relatório: a plataforma invoca esse URL retornado da função.

Relatórios de eventos

Só é possível fazer relatórios de eventos depois que os relatórios de impressões do leilão são concluídos. O SDK de venda é responsável por relatar qualquer evento. A plataforma expõe uma API que recebe uma ReportEventRequest que especifica o leilão executado recentemente, a chave de evento informada, os dados associados a essa chave, se o relatório precisa ser enviado ao comprador ou ao vendedor (ou ambos) e um evento de entrada opcional para eventos de anúncios. O cliente define a chave de evento e a coleta de dados a serem informados.

ReportEventRequest request = new ReportEventRequest(
  AdSelectionId = ad_selection_id,
  event_key = "view"
  event_data = "{ "viewTimeInSeconds" :1 }",
  reporting_destinations =
    FLAG_REPORTING_DESTINATION_SELLER |
      FLAG_REPORTING_DESTINATION_BUYER,
  input_event = clickInputEvent // or null for view
  )

reportEvent(request)

Entrada:

  • O ad_selection_id precisa ser um AdSelectionId de um leilão executado recentemente e extraído do AdSelectionOutcome.
  • A event_key é uma string definida para o lado do vendedor que descreve o evento de interação.
  • event_data é uma string que representa os dados associados à event_key.
  • reporting_destinations é um bitmask definido usando flags fornecidas pela plataforma. Pode ser FLAG_REPORTING_DESTINATION_SELLER, FLAG_REPORTING_DESTINATION_BUYER ou ambos.
  • input_event (opcional) é usado para integração com a API Attribution Reporting. Ele é um objeto InputEvent (para um evento de clique) ou nulo (para um evento de visualização). Consulte Integração da API Attribution Reporting para mais detalhes sobre esse parâmetro.

Depois que o SDK de venda invoca reportEvent e, dependendo da flag reporting_destinations, a plataforma tenta fazer a correspondência da event_key com as chaves registradas por compradores e vendedores nas funções JavaScript reportWin e reportResult. Se houver uma correspondência, a plataforma fará o POST do event_data no reporting_url associado. O tipo de conteúdo da solicitação é de texto simples, com o corpo sendo event_data. Essa solicitação é feita da melhor maneira possível e vai falhar silenciosamente no caso de um erro de rede, resposta de erro do servidor ou se nenhuma chave correspondente tiver sido encontrada.

Integração da API Attribution Reporting

Para oferecer suporte aos compradores que participam de um leilão da Protected Audience, oferecemos funcionalidade entre APIs nas APIs Protected Audience e Attribution Reporting (ARA). Essa funcionalidade permite que as adtechs avaliem a performance de atribuição em várias táticas de remarketing, para que possam entender quais tipos de público-alvo geram o ROI mais alto.

Com essa integração entre APIs, as adtechs podem:

  • Crie um mapa de chave-valor de URIs a ser usado para 1) relatórios de interação com anúncios e 2) registro de origem.
  • Incluir dados de leilão do leilão da Protected Audience no mapeamento de chaves do lado da origem para gerar relatórios de resumo agregados (usando a API Attribution Reporting). Consulte a proposta de design da ARA para mais informações.

Quando um anúncio é mostrado ou o usuário clica nele:

  • O URL usado para informar essas interações de eventos usando a API Protected Audience vai fornecer os dados necessários ao comprador que serão usados para registrar uma visualização ou um clique como uma fonte qualificada com a API Attribution Reporting.
  • A adtech pode transmitir CustomAudience ou outras informações contextuais relevantes sobre o anúncio, como posição do anúncio ou duração da visualização, usando esse URL para que os metadados sejam propagados para os relatórios de resumo quando a adtech estiver analisando a performance agregada da campanha.

Como ativar o registro de fonte

reportEvent() aceitará um novo parâmetro opcional InputEvent. Os compradores vencedores que registram beacons de anúncio podem escolher quais relatórios reportEvent são registrados nas APIs Attribution Reporting como uma fonte registrada. O cabeçalho da solicitação "Attribution-Reporting-Eligible" é adicionado a todas as solicitações de relatórios de eventos enviadas de reportEvent(). Todas as respostas com cabeçalhos ARA apropriados serão analisadas da mesma forma que qualquer outra resposta normal de registro de origem ARA seria. Consulte a explicação da API Attribution Reporting para saber como registrar um URL de origem.

Como a ARA no Android oferece suporte a eventos de visualização e clique, InputEvents são usados para distinguir entre os dois tipos. Assim como no registro de origem ARA, a API reportEvent() vai interpretar uma InputEvent verificada pela plataforma como um evento de clique. Se o InputEvent estiver ausente, nulo ou inválido, o registro da fonte será considerado uma visualização.

O eventData pós-leilão pode conter informações sensíveis. Por isso, a plataforma descarta o eventData nas solicitações de registro de origem redirecionadas.

Exemplo de relatório de engajamento e conversão

Neste exemplo, vamos analisar o comprador do ponto de vista do comprador, que está interessado em associar os dados do leilão, do anúncio renderizado e do app de conversão juntos.

Nesse fluxo de trabalho, o comprador coordena com o vendedor para enviar um ID exclusivo ao leilão. Durante o leilão, o comprador envia esse ID exclusivo com os dados dele. Durante a renderização e a conversão, os dados do anúncio renderizado também são enviados com o mesmo ID exclusivo. Depois, o ID exclusivo pode ser usado para associar esses relatórios.

Fluxo de trabalho: antes do início do leilão, o comprador envia um ID exclusivo ao vendedor como parte da resposta do lance em tempo real ("RTB") programático. O ID pode ser definido como uma variável, como auctionId. O ID é transmitido como perBuyerSignals no auctionConfig e fica disponível na lógica de lances do comprador.

  1. Durante a execução de reportWin, o comprador pode registrar um beacon de anúncio que será acionado durante a renderização do anúncio e para eventos de interação específicos (registerAdBeacon()). Para associar indicadores de leilão a um evento de anúncio, defina auctionId como um parâmetro de consulta do URL de beacon.
  2. Durante a renderização do anúncio, os beacons registrados durante o leilão podem ser acionados ou aprimorados com dados de evento. O vendedor precisa acionar reportEvent() e transmitir os dados no nível do evento. A plataforma vai dar um ping no URL de beacon de anúncio registrado do comprador relacionado ao reportEvent() acionado.
  3. O comprador vai registrar o anúncio com a API Attribution Reporting respondendo às solicitações de beacon de anúncio com o cabeçalho Attribution-Reporting-Register-Source. Para associar indicadores de leilão a um evento de conversão, defina auctionId no URL de registro de origem.

Após o processo acima, o comprador terá um relatório de leilão, de interação e de conversão, que podem ser correlacionados usando o ID exclusivo que pode ser associado entre si.

Um fluxo de trabalho semelhante vai ser aplicado a um vendedor se ele precisar de acesso aos dados de atribuição. O vendedor também pode usar um ID exclusivo para enviar com registerAdBeacon(). A chamada reportEvent() contém uma propriedade de destino que pode ser usada para enviar o relatório ao comprador e ao vendedor.

Servidor confiável gerenciado pela plataforma de adtech

Atualmente, a lógica de seleção de anúncios exige informações em tempo real, como o nível de uso de um orçamento, a fim de determinar se os anúncios candidatos precisam ser selecionados para o leilão. As plataformas de compra e venda poderão receber essas informações nos servidores em que operam. Para minimizar o vazamento de informações sensíveis por esses servidores, a proposta estabelece estas restrições:

  • O comportamento desses servidores, descrito posteriormente nesta seção, não causa vazamento de informações dos usuários.
  • Os servidores não criam perfis de pseudônimos com base nos dados visto, ou seja, eles precisam ser "confiáveis".

Compra: após iniciar a lógica de lances de compra, a plataforma realiza uma busca HTTP de dados de lances confiáveis no servidor confiável. O URL é composto anexando o URL e as chaves presentes nos metadados de indicadores de lances confiáveis do público-alvo personalizado que está sendo processado. A busca é feita apenas ao processar anúncios dos públicos-alvo personalizados contidos no dispositivo. Nesta etapa, a plataforma de compra pode aplicar orçamentos, verificar o estado de pausa e retomada da campanha, executar segmentação, entre outros.

Confira abaixo um exemplo de URL para buscar dados de lances confiáveis com base nos metadados do indicador de lances confiáveis do público-alvo personalizado:

https://www.kv-server.example/getvalues?keys=key1,key2

A resposta do servidor precisa ser um objeto JSON com chaves key1, key2 etc., e com os valores que vão ser disponibilizados para as funções de lance do comprador.

Venda: semelhante ao fluxo de compra acima, a plataforma de venda pode querer buscar informações sobre criativos considerados no leilão. Por exemplo, é possível que um editor queira garantir que determinados criativos não sejam mostrados no app devido a questões de brand safety. Essas informações podem ser buscadas e disponibilizadas para a lógica de leilão da venda. Semelhante à pesquisa no servidor confiável da plataforma de compra, a pesquisa no servidor confiável da plataforma de venda também acontece por uma busca HTTP. O URL é composto anexando o URL de indicadores de pontuação confiáveis a URLs de renderização dos criativos para os quais os dados precisam ser buscados.

Confira abaixo um exemplo de URL para buscar informações sobre criativos considerados no leilão, com base nos URLs de renderização de criativos:

https://www.kv-server.example/getvalues?renderUrls=render_url1,render_url2

A resposta do servidor precisa ser um objeto JSON com chaves de URLs de renderização enviados na solicitação.

Esses servidores funcionam de maneira confiável para oferecer vários benefícios de segurança e privacidade:

  • O valor de retorno do servidor para cada chave só pode ser considerado confiável de acordo com a própria chave.
  • O servidor não realiza a geração de registros do evento.
  • O servidor não tem outros efeitos colaterais relacionados a essas solicitações.

Como mecanismo temporário, o comprador e o vendedor podem buscar esses indicadores de lance em qualquer servidor, incluindo aqueles que eles mesmos operam. No entanto, na versão de lançamento, a solicitação vai ser enviada somente a um servidor de tipo de chave-valor confiável.

Compradores e vendedores podem usar um mesmo servidor de tipo de chave-valor confiável para plataformas compatíveis com o Sandbox de privacidade no Android e na Web.