Partilhar via

Inscrever-se na API de Seleção de Anúncios

  • Artigo

A API de Seleção de Anúncios fornece anúncios relevantes para o utilizador no seu site sem utilizar cookies de terceiros. Veja Descrição Geral da Seleção de Anúncios no privacy-preserving-ads repositório.

A API de Seleção de Anúncios pode ser utilizada por:

  • Vendedores que executam uma plataforma do lado da oferta (SSP), que pode utilizar a API para fornecer anúncios de maior qualidade aos seus editores.
  • Compradores que executam uma plataforma do lado da procura (DSP), que podem utilizar a API para melhorar a eficácia das campanhas publicitárias.

Para começar a utilizar a API de Seleção de Anúncios e testar o fluxo ponto a ponto, inscreva-se na pré-visualização limitada da API de Seleção de Anúncios.

Enquanto vendedor que opera uma plataforma do lado da oferta ou um comprador que opera uma plataforma do lado da procura, utilize este guia para:

  • Inscreva-se na pré-visualização limitada da API de Seleção de Anúncios ao registar-se na versão de avaliação de origem.
  • Conclua o atestado de API ao publicar o ficheiro JSON dos atestados.
  • Configurar um ambiente de avaliação com um fornecedor de cloud suportado.
  • Veja a documentação da API de Seleção de Anúncios.
  • Preparar as Funções User-Defined (UDFs).
  • Implemente os seus serviços no Azure.
  • Teste a API de Seleção de Anúncios no seu site.

Inscrição de atestado e inscrição alfa

Quando e onde está disponível a pré-visualização?

As versões do Microsoft Edge a partir da versão 130.0.2808.0 têm suporte para a API de Seleção de Anúncios numa pré-visualização limitada de opt-in para programadores fora do Espaço Económico Europeu (EEE) e do Reino Unido (Reino Unido).

Sinalizadores para teste

Para alterar as funcionalidades da plataforma da API de Seleção de Anúncios no seu computador programador, utilize os sinalizadores de teste da API de Seleção de Anúncios em edge://flags#edge-ad-selection-api:

Os sinalizadores da

O sinalizador da API de Seleção de Anúncios ativa a API de Seleção de Anúncios e as funcionalidades associadas, tais como:

  • Relatórios de Atribuição.
  • Molduras Vedadas.
  • Armazenamento Partilhado.
  • Agregação Privada.

Requisitos e processos de inscrição e atestado

Os programadores interessados em testes alfa podem aderir à avaliação de origem da API de Seleção de Anúncios. Esta avaliação de origem permite testes ponto a ponto das funcionalidades da API de Seleção de Anúncios, abrangendo a utilização da API e a implementação de imagens de contentor seguras.

Para cada domínio de nível superior que pretende utilizar com a API de Seleção de Anúncios, preencha o formulário Registo de Avaliação de Origem desse domínio e, em seguida, submeta o formulário.

Para se inscrever na avaliação de origem da API de Seleção de Anúncios de um domínio:

  1. Abra as Avaliações de Origem do Microsoft Edge numa nova janela ou separador:

    A lista de avaliação de origem da

  2. Na secção API de Seleção de Anúncios , clique no botão Registar . O formulário Registo de Avaliação de Origem é aberto:

    Formulário de registo

  3. Preencha o formulário.

    • Na caixa de texto Domínio , introduza um único domínio de nível superior. Por exemplo, um domínio de nível superior é contoso.examplee, opcionalmente, inclui subdomínios como subdomain.contoso.example.

    • Na secção Suporte de Subdomínio , selecione o botão de opção Sim ou Não .

    • Na caixa de texto Endereço do Email, forneça um contacto de programador válido para o domínio.

    • Na caixa de texto Nome da Avaliação de Origem , introduza AdSelectionAPI (sem espaços). Este é o ID desta versão de avaliação de origem.

  4. Clique no botão Submeter .

    É gerado um token de avaliação de origem para o domínio de nível superior e é enviado para si.

  5. Crie um ficheiro com o nome ad-selection-attestations.jsone aloje o ficheiro no domínio de nível superior, no /.well-known/ diretório . Por exemplo:

    https://contoso.example/.well-known/ad-selection-attestations.json

    O ad-selection-attestations.json ficheiro tem de ser publicado no prazo de 30 dias após a receção do token OT. É necessário alojar este ficheiro JSON para concluir o atestado e permitir que o código aceda à API de Seleção de Anúncios para testar a API de Seleção de Anúncios com clientes microsoft Edge suportados.

Ficheiro JSON de exemplo

O ficheiro JSON dos atestados tem de ter o nome ad-selection-attestations.jsone tem de estar em conformidade com as seguintes normas abaixo. Segue-se um exemplo de um ad-selection-attestations.json ficheiro:

{
    "ad_selection_api_attestations": [
        {
            "attestation_parser_version": "2",
            "attestation_version": "2",
            "privacy_policy": [
                "https://contoso.example/privacy/"
            ],
            "ownership_token": "<Your Unique Token Here>",
            "enrollment_site": "https://contoso.example/",
            "platform_attestations": [
                {
                    "platform": "edge",
                    "attestations": {
                        "ad_selection_api": {
                            "ServiceNotUsedForIdentifyingUserAcrossSites": true/false
                        },
                        "attribution_reporting_api": {
                            "ServiceNotUsedForIdentifyingUserAcrossSites": true/false
                        },
                        "shared_storage_api": {
                            "ServiceNotUsedForIdentifyingUserAcrossSites": true/false
                        },
                        "private_aggregation_api": {
                            "ServiceNotUsedForIdentifyingUserAcrossSites": true/false
                        }
                    }
                },
                {
                    "platform": "android",
                    "attestations": {}
                }
            ]
        }
    ]
}
Campos e valores importantes

  • O ad-selection-attestations.json ficheiro tem de incluir o token de avaliação de origem que foi gerado e enviado para si para este domínio de nível superior. "ownership_token": é o token de avaliação de origem que foi gerado ao registar este domínio na versão de avaliação da origem da API de Seleção de Anúncios .

  • "platform_attestations": Na secção, "platform": tem de ser "edge" ou "android".

  • O ficheiro tem de incluir uma lista de APIs (funcionalidades que estão associadas à API dos Serviços de Anúncios). "platform_attestations": Na secção, os membros válidos de "attestations": são os seguintes:

    • "ad_selection_api":- A API de main, para lógica de leilão privado.
    • "attribution_reporting_api": - Relatórios de atribuição.
    • "shared_storage_api": - Armazenamento partilhado.
    • "private_aggregation_api": - Agregação privada.
    • Requisitos:
      • Cada "..._api": entrada tem de ter um único campo, "ServiceNotUsedForIdentifyingUserAcrossSites":, com um true ou false valor. true significa que este serviço não é utilizado para identificar o utilizador entre sites. false significa que este serviço é utilizado para identificar o utilizador entre sites.

Implementar os serviços da API de Seleção de Anúncios

A API de Seleção de Anúncios utiliza um ambiente de execução fidedigno (TEE) para fornecer um nível de garantia para a integridade dos dados, confidencialidade dos dados e integridade do código; veja Computação Confidencial: Hardware-Based Execução Fidedigna para Aplicações e Dados. Os serviços fornecidos pela API de Seleção de Anúncios têm de ser executados num TEE para proteger os dados utilizados por estes serviços.

Os Serviços de Seleção de Anúncios em execução num TEE devem ser implementados numa plataforma na cloud que suporte as funcionalidades de segurança necessárias. Inicialmente, os serviços podem ser implementados no Azure com contentores confidenciais do ACI; veja Contentores confidenciais no Instâncias de Contêiner do Azure.

A API de Seleção de Anúncios fornece diferentes serviços que precisam de ser implementados por vendedores ou compradores.

Imagens para implementar serviços

Adicione as funções User-Defined (UDFs) nas imagens fornecidas dos serviços. As Funções User-Defined podem executar lógica de negócio personalizada. As Funções User-Defined são executadas em contentores privados nos serviços implementados.

Cada imagem define um serviço. Algumas imagens não contêm UDFs e consistem inteiramente em código predefinido. Algumas imagens contêm UDFs, como funções com um corpo vazio ou código inicial, que são as Funções de User-Defined relevantes para esse serviço. Preencha os corpos das Funções User-Defined nestas imagens com o seu próprio código personalizado.

A Microsoft fornece uma imagem para cada serviço, que pode ser implementada num fornecedor de cloud. Estas são as imagens públicas que têm de ser utilizadas para a implementação. Apenas as imagens oficiais da Microsoft podem realizar leilões privados.

Imagens para implementação:

Serviços para vendedores

Serviço Descrição
SellerFrontEnd Fornece um /SelectAd ponto final HTTPS, que recebe pedidos do serviço de anúncios não fidedigno do vendedor para iniciar o fluxo de leilão da Audiência Protegida.
Leilão Fornece um /ScoreAds ponto final, que recebe pedidos do serviço SellerFrontEnd , que contém licitações que estão a participar no leilão. Responde com um valor de classificação que o serviço SellerFrontEnd utiliza para escolher o vencedor.
Chave/Valor Recebe pedidos do serviço SellerFrontEnd , que contêm chaves de pesquisa das ofertas dos compradores (como ad_render_urls). Devolve sinais de classificação em tempo real necessários para o leilão. É executado no modo Bring Your Own Service (BYOS), pelo que o vendedor não precisa de implementar este serviço num ambiente de execução fidedigno (TEE) e, em vez disso, pode utilizar a imagem fornecida pela Microsoft.

Serviços para compradores

Serviço Descrição
BuyerFrontEnd Fornece um /GetBids ponto final, que recebe pedidos do serviço SellerFrontEnd para iniciar o fluxo de licitação.
Licitação Fornece um /GenerateBids ponto final, que recebe pedidos do serviço BuyerFrontEnd para processar a licitação e gerar uma oferta. Gera uma oferta, escolhe o vencedor e seleciona a faixa a ser composta.
Chave/Valor Recebe pedidos do serviço BuyerFrontEnd e devolve dados de comprador em tempo real necessários para licitação, correspondentes a chaves de pesquisa do Interest Grupos. Tal pedido ocorre uma vez por fluxo de trabalho. É executado no modo Bring Your Own Service (BYOS).
Chave/Valor do & de Seleção de Licitação Recebe pedidos do serviço de Licitação para selecionar e devolver faixas de anúncios adicionais (candidatos) que podem participar na licitação. A Seleção de Licitação & serviço Chave/Valor também pode devolver sinais adicionais necessários para licitação. O serviço Licitação pode enviar vários pedidos para o serviço Seleção de Licitação & Chave/Valor ou pode optar por não enviar pedidos, uma vez que o serviço Chave /Valor & Seleção de Licitação é opcional. A Seleção de Licitação & serviço Chave/Valor tem de ser implementado num ambiente de execução fidedigno (TEE).
K-Anonimato Recolhe contadores de k-anonimato e verifica se o criativo do anúncio vencedor passa o k-anonimato marcar.

Funções Definidas pelo Usuário

Os vendedores e compradores têm de fornecer o seu próprio código personalizado como funções User-Defined (UDFs) que são executadas em contentores privados nos serviços implementados. Estas Funções User-Defined podem executar lógica de negócio personalizada.

Cada comprador ou vendedor pode implementar várias instâncias de um determinado serviço, tais como:

  • SellerFrontEnd e Leilão.
  • BuyerFrontend, Bidding e K-Anonymity.

Alguns destes serviços têm uma entrada que é uma worklet JavaScript que define User-Defined Funções.

Funções de User-Defined para vendedores
UDF Serviço no qual o UDF é executado Descrição
scoreAd() Leilão Gera uma pontuação para a oferta de cada comprador ou rejeita a oferta. Esta pontuação é então utilizada pelo serviço SellerFrontEnd , para escolher um vencedor entre todos os compradores.
reportResult() SellerFrontEnd Para relatórios ao nível do evento. É executado no serviço SellerFrontEnd após a escolha do vencedor final. Notifica o vendedor sobre o licitador vencedor e fornece o valor da oferta.
Funções de User-Defined para compradores
UDF Serviço no qual o UDF é executado Descrição
generateBids() Licitação Gera uma oferta e escolhe a faixa que será apresentada.
reportWin() SellerFrontEnd Para relatórios ao nível do evento. É executado no serviço SellerFrontEnd , se a oferta do comprador ganhar o leilão. Notifica o comprador de que ganhou o leilão e gera URLs de notificação que serão acionados mais tarde, como durante a composição de faixas ou outros eventos de cliente.
getValues() Chave/Valor do & de Seleção de Licitação É executado no serviço Seleção de Licitação & Chave/Valor , se o comprador utilizar esse serviço. Permite a execução de código personalizado para pesquisa e seleção de dados.

Guia de implantação

Para implementar o serviço API de Seleção de Anúncios no Azure:

  1. Crie uma conta do Azure e crie uma subscrição no Microsoft Azure.

  2. Selecione a opção Contentores confidenciais do ACO .

  3. Aceda a Scripts de implementação do Terraform numa nova janela ou separador e, em seguida, transfira os scripts de implementação do Terraform e veja a documentação de implementação. Nota: Certifique-se de que o hash da imagem que transferiu corresponde ao hash no script que transferir.

  4. Os scripts do Terraform já incluem ligações para imagens públicas fornecidas pela Microsoft. Escolha os serviços necessários e implemente-os ao seguir os passos no .readme.md

    1. Defina quaisquer sinalizadores específicos para o seu ambiente, incluindo localizações de leilão de worklets.

    2. Configure todos os pré-requisitos e prepare todas as ferramentas para implementação.

    3. Crie Recursos do Azure e execute o script do Terraform que termina a implementação.

  5. Desenvolva worklets, incluindo user-defined-function (UDF) e inicie serviços da API de Seleção de Anúncios.

Utilizar a API de Seleção de Anúncios no seu site

Para começar a utilizar a API de Seleção de Anúncios, os vendedores e compradores têm de modificar o código JavaScript dos respetivos sites que é executado quando o browser é o Microsoft Edge.

  • Vendedores: para executar leilões privados, obter grupos de interesses e fazer relatórios, atualize o código nos sites dos editores.

  • Compradores: para criar grupos de interesses e armazená-los no browser, atualize o código nos sites dos seus parceiros de publicidade. Pode utilizar o mecanismo de delegação para restringir e permitir a criação do Grupo de Interesses em domínios de terceiros.

Para saber mais sobre que métodos de API estão disponíveis e para ver o código de exemplo, veja Detalhes da API de Seleção de Anúncios.

Fornecer feedback sobre a versão de avaliação de origem

Para fornecer feedback sobre a versão de avaliação da origem da API de Seleção de Anúncios:

  1. Aceda ao portal microsoft Edge Origin Trials em Github.io.

  2. Aceda à linha da versão de avaliação da origem da API de Seleção de Anúncios .

  3. Clique no botão problemas na linha. O privacy-preserving-ads repositório é aberto.

  4. Submeta um novo problema ou clique no separador Problemas para ver os problemas.

Confira também

Estrutura e documentos técnicos

Imagens para implementação:

Scripts de implementação:

Avaliações de origem:

Ambiente de execução fidedigno (TEE):

Azure: