Testar a experiência completa de perguntas e respostas para Web localmente

1. Introdução

Os serviços de lances e leilões (B&A) são compostos por quatro serviços para compradores e vendedores facilitarem um leilão com Protected Audience:

Pilha do comprador:

• Serviço de front-end para compradores
• Serviço de lances

Pilha de vendas:

• Serviço de front-end do vendedor
• Serviço de leilão

Este codelab mostra como configurar e testar a configuração completa no seu ambiente local. O tutorial deve levar aproximadamente uma hora, sem contar o tempo inicial de build do serviço.

Mesmo que você trabalhe apenas no código do lado da compra ou da venda, é útil configurar o fluxo completo no seu ambiente local para entender melhor como as pilhas de comprador e vendedor funcionam juntas. Ao configurar as duas stacks, você terá mais confiança ao fazer a integração com a stack de comprador ou vendedor de outra parte. Testar os serviços localmente também economiza seu custo de desenvolvimento.

Neste codelab, vamos usar o B&A Local Testing App como um guia.

O app de teste local complementar hospeda vários recursos de comprador e vendedor usados em um leilão de B&A. O app também oferece uma interface em http://localhost:3000, em que é possível simular várias configurações de leilão.

2. configuração do ambiente

2.1 Preparar uma máquina Linux

Use uma máquina Linux local ou provisione uma VM Linux do provedor de nuvem de sua escolha. Para melhorar o tempo de build, recomendamos pelo menos 16 núcleos como mínimo e preferimos 32 ou mais.

Vamos carregar uma página HTML de http://localhost:3000 desta máquina. Se a VM não fornecer uma GUI, verifique se a porta 3000 está acessível à sua máquina local para que você possa se conectar a ela.

2.2 Instalar o Docker

Usamos o Docker para executar os serviços e o aplicativo de teste local.

Vamos usar o script de conveniência para instalar o Docker em um ambiente de teste.

# Install Docker
> curl -fsSL https://get.docker.com -o get-docker.sh
> sudo sh get-docker.sh

# Set up sudo-less Docker
> sudo groupadd docker
> sudo usermod -aG docker $USER
> newgrp docker

# Test
> docker run hello-world

Aviso: com a configuração sem sudo, o grupo do Docker concede privilégios de nível raiz ao usuário. Leia o guia do Docker sem sudo para saber mais.

2.3 Inicie o app complementar de teste local

O app complementar oferece recursos como scripts de simulação de lances ou pontuação e endpoints de simulação de BYOS de K/V. O app precisa ser iniciado antes da execução dos serviços de B&A para que os recursos possam ser carregados neles.

Extraia o repositório do app de teste local:

git clone https://github.com/privacysandbox/bidding-auction-local-testing-app.git

Na raiz do repositório, execute o script de configuração:

./setup

O script de configuração vai criar a rede Docker ba-dev, gerar certificados SSL e criar a imagem do app de teste.

Quando o build for concluído, execute o script de inicialização:

./start

3. Criar e executar a B&A localmente

3.1 Puxe para baixo os serviços de B&A

Vamos executar dois conjuntos de serviços de B&A na mesma máquina. Por isso, vamos extrair o repositório para duas pastas diferentes.

Conjunto A:

Extraia o repositório de B&A:

git clone https://github.com/privacysandbox/bidding-auction-servers.git bidding-auction-servers-set-a

Conjunto B

Extraia o repositório de B&A:

git clone https://github.com/privacysandbox/bidding-auction-servers.git bidding-auction-servers-set-b
`

3.2 Criar os serviços

Na pasta raiz de cada pasta do B&A, execute o seguinte comando para criar todos os quatro serviços:

production/packaging/build_and_test_all_in_docker \
  --service-path bidding_service \
  --service-path auction_service \
  --service-path buyer_frontend_service \
  --service-path seller_frontend_service \
  --platform gcp \
  --instance local \
  --no-precommit \
  --no-tests \
  --build-flavor non_prod \
  --gcp-skip-image-upload

Esse comando vai criar uma instância local do build de desenvolvimento (non_prod) para o Google Cloud (gcp) de todos os quatro serviços. Atualize a flag --platform para o provedor de nuvem de sua escolha, se necessário. Para saber mais sobre as flags de build, consulte o arquivo build_and_test_all_docker.

O build inicial pode levar duas horas se você usar uma máquina de 64 núcleos. O tempo de build é dimensionado linearmente de acordo com a contagem de núcleos. Se você estiver em uma máquina de 32 núcleos, pode levar 4 horas. Se você estiver usando uma máquina de 16 núcleos, pode levar 8 horas.

Builds subsequentes usam o cache, e cada build leva de 5 a 20 minutos.

Quadrinho relevante do xkcd:

Dois programadores se divertindo enquanto um build está em execução.

Conheci Randall Munroe, do xkcd, enquanto escrevia este codelab e contei que adicionei essa história em quadrinhos aqui.

3.3 Executar os serviços

Para nossos testes, vamos executar oito serviços (quatro serviços por pilha). Cada comando é configurado para usar os recursos fornecidos pelo app de teste local. É altamente recomendável usar um gerenciador de janelas, como o tmux.

Abra pelo menos mais oito janelas de terminal e execute os comandos a seguir em cada sessão.

O servidor do app de teste local precisa estar em execução em um processo separado, já que os scripts de lances e pontuação serão veiculados pelo app.

3.3.1 Comandos do conjunto A

3.3.2 Comandos do conjunto B

3.3.2 Variáveis de ambiente para os scripts de inicialização local

As seguintes variáveis de ambiente podem ser usadas para controlar o comportamento de inicialização.

4. Testar com a invocação segura na linha de comando

4.1 Teste de SFE

Você também pode usar a ferramenta Secure Invoke incluída no pacote de serviços de B&A para chamar os serviços diretamente da linha de comando.

4.1.2 Payload de SelectAd do SFE

A seguinte solicitação JSON foi preenchida com a configuração de leilão de B&A de vendedor único do SSP-BA:

{
  "auction_config": {
    "seller": "https://localhost:6002",
    "auction_signals": "{\"testKey\":\"someValue\"}",
    "seller_signals": "{\"testKey\":\"someValue\"}",
    "buyer_list": [
      "https://localhost:5003",
      "https://localhost:5004"
    ],
    "per_buyer_config": {
      "https://localhost:5003": { "buyer_signals": "{\"testKey\":\"someValue\"}" },
      "https://localhost:5004": { "buyer_signals": "{\"testKey\":\"someValue\"}" }
    }
  },
  "raw_protected_audience_input": {
    "publisher_name": "http://localhost:4001",
    "generation_id": "1210718540",
    "enable_debug_reporting": true,
    "raw_buyer_input": {
      "https://localhost:5003": {
        "interest_groups": [
          {
            "name": "dsp-x-demo",
            "ad_render_ids": ["1234"],
            "bidding_signals_keys": ["demo-key"],
            "browser_signals": { "bid_count": "1", "join_count": "1", "prev_wins": "[]" },
            "user_bidding_signals": "[1, 2, 3]"
          }
        ]
      },
      "https://localhost:5004": {
        "interest_groups": [
          {
            "name": "dsp-x-demo",
            "ad_render_ids": ["1234"],
            "bidding_signals_keys": ["demo-key"],
            "browser_signals": { "bid_count": "1", "join_count": "1", "prev_wins": "[]" },
            "user_bidding_signals": "[1, 2, 3]"
          }
        ]
      }
    }
  }
}

Salve o arquivo como sfe-test.json na pasta raiz do repositório de serviços de B&A do Set A. O script de build de B&A vai copiar os arquivos na pasta raiz do repositório para a pasta /src/workspace da imagem do Docker.

4.1.2 Chamar o SFE com a invocação segura

Execute o seguinte comando na pasta raiz do repositório de serviços do B&A:

DOCKER_NETWORK=ba-dev ./builders/tools/bazel-debian run //tools/secure_invoke:invoke \
  -- \
  -target_service=sfe \
  -input_file=/src/workspace/sfe-test.json \
  -host_addr=192.168.84.104:50053 \
  -client_ip=192.168.84.100 \
  -insecure=true

Se as pilhas de B&A estiverem configuradas corretamente, você vai receber a seguinte resposta de sucesso:

{"adRenderUrl":"https://localhost:5004/ad.html","interestGroupName":"dsp-x-demo","interestGroupOwner":"https://localhost:5004","score":39,"bid":39,"biddingGroups":{"https://localhost:5003":{"index":[0]},"https://localhost:5004":{"index":[0]}}}

4.2 Teste de BFE

4.2.1 Solicitação de GetBids do BFE

{
  "buyer_input": {
    "interest_groups": {
      "name": "dsp-x-demo",
      "ad_render_ids": ["1234"],
      "bidding_signals_keys": ["demo-key"],
      "browser_signals": { "bid_count": "1", "join_count": "1", "prev_wins": "[]" }
    }
  },
  "auction_signals": "{\"testKey\":\"someValue\"}",
  "buyer_signals": "{\"testKey\":\"someValue\"}",
  "seller": "https://localhost:6002",
  "publisher_name": "http://localhost:4001",
  "enable_debug_reporting": true,
  "client_type": "CLIENT_TYPE_BROWSER"
}

Salve o arquivo como bfe-test.json na pasta raiz do repositório de serviços do B&A.

4.2.2 Chamar o BFE com Secure Invoke

Execute o seguinte comando na pasta raiz do repositório de serviços do B&A:

DOCKER_NETWORK=ba-dev ./builders/tools/bazel-debian run //tools/secure_invoke:invoke \
  -- \
  -target_service=bfe \
  -input_file="/src/workspace/bfe-test.json" \
  -host_addr="192.168.84.102:50051" \
  -client_ip=192.168.84.100 \
  -insecure=true

Se as pilhas de B&A estiverem configuradas corretamente, o BFE vai retornar a seguinte resposta:

{"bids":[{"bid":6,"render":"https://localhost:5003/ad.html","interestGroupName":"dsp-x-demo"}],"updateInterestGroupList":{}}

4.3 Verifique os registros do SFE

Acesse o terminal e verifique os registros do SFE. Vamos analisar alguns dos registros importantes na saída.

4.3.1 Payload criptografado da solicitação SelectAd

Nesta saída de registro do SFE, encontramos o payload criptografado da chamada navigator.getInterestGroupAdAuctionData(). Esse payload é gerado pelo navegador, enviado da tag para o SAS e, em seguida, encaminhado pelo SAS para o SFE:

I1210 21:20:47.266673      37 select_ad_reactor.cc:228] Protected auction ciphertext: AEAAIAABAAKg3OQSSLEBMR1MmJiwfOT8uef41iE+DQIvKUowsQvVcGbWZ+r17ff2r/iTbEnwqLPtpAxSTy77mi+cVV5cKjkKb4piaZnKiCDIMCyEvrQUD4+BG+HgrbUFhqiWPmQhNThvInMaHuYrXG7xushbRtvSPsVzEl6iBZcLZzD7W3CHMFK7bnJ+ufu52W6B7/8dOQ1gZW6SpwXMGNcrurTGoucbwbZRIPqCcbZk76J1gB69wrDYRo1wQ6jmBleLM36nulxbEj/sHhpQIgr895aKqEGQ3Fy+/HHPTO+zHphcX44YeF6mZ/I+WxZTDxCi1x27nI4yvzC8vI4a/giJN5XUlJZGb/fMrj3/Qly+gwJ8lbxdX+4GWTooDoS4MTtiBpJqh9wkIQ5XwfO54p8Kv6j/tk+51hOfVkOdtGwX0LvVrWT9PiJOJHa23nZ1fLg/22mTe05xdbR3WVeA+xiO9YwF4ozyCYDRUkDyWB/3k9RuaaT9H5S1szVpuOuD2nYSRpT9svmpfG4kipiS6BTPZPX2whDlukpuuoFgdiDtH6cFShNhZ5C47R0ayAvaZ1QSpOZMWfA6pdl4nhvNLpOKesKY/KFDEBzpUXRDsQWsfvmdqFl1mCeX9rOrEc9rodYVLXXhM8GPycehHmvqkccTBW6kipOQlmnSdIYaFmtWSFpUrzxajGkct3mZdTjVjOf...

4.3.2 Payload descriptografado

Nesta saída, encontramos o payload descriptografado da chamada navigator.getInterestGroupAdAuctionData():

I1210 21:20:47.267590      37 select_ad_reactor.cc:347]  (generationId: c2824bfc-d515-4a1a-9de9-7660ad963252) Decoded BuyerInput:
https://localhost:5003 : {interest_groups { name: "dsp-x-demo" bidding_signals_keys: "demo-key" browser_signals { join_count: 1 recency: 7 prev_wins: "[]" } }}

4.3.3 Solicitação GetBids para BFE

A solicitação GetBids é enviada do SFE para o BFE:

I1210 21:20:47.267710      37 select_ad_reactor.cc:751]  (generationId: c2824bfc-d515-4a1a-9de9-7660ad963252) Getting bid from a BFE
I1210 21:20:47.267729      37 buyer_frontend_async_client.cc:52] Raw request:
buyer_input {
  interest_groups {
    name: "dsp-x-demo"
    bidding_signals_keys: "demo-key"
    browser_signals {
      join_count: 1
      recency: 7
      prev_wins: "[]"
    }
  }
}
auction_signals: "{\"testKey\":\"someValue\"}"
buyer_signals: "{\"testKey\": \"someValue\"}"
seller: "https://localhost:6002"
publisher_name: "localhost"
enable_debug_reporting: true
log_context {
  generation_id: "c2824bfc-d515-4a1a-9de9-7660ad963252"
}
client_type: CLIENT_TYPE_BROWSER

4.3.4 GetBids resposta da BFE

O BFE responde com o lance:

I1210 21:20:47.282549      41 select_ad_reactor.cc:856]  (generationId: c2824bfc-d515-4a1a-9de9-7660ad963252) Received response from a BFE ...
I1210 21:20:47.282552      41 select_ad_reactor.cc:859]  (generationId: c2824bfc-d515-4a1a-9de9-7660ad963252)
GetBidsResponse:
bids {
  bid: 9
  render: "https://localhost:5003/ad.html"
  interest_group_name: "dsp-x-demo"
}
update_interest_group_list {
}

4.3.5 Solicitação ScoreAds ao serviço de leilão

Depois que os lances são recebidos, a chamada ScoreAds é feita pelo SFE ao serviço de leilão para cada lance:

I1210 21:20:47.287898      18 select_ad_reactor.cc:1280]  (generationId: c2824bfc-d515-4a1a-9de9-7660ad963252) ScoreAdsRawRequest:
ad_bids {
  bid: 9
  render: "https://localhost:5003/ad.html"
  interest_group_name: "dsp-x-demo"
  interest_group_owner: "https://localhost:5003"
  join_count: 1
  k_anon_status: true
}
seller_signals: "{\"testKey\":\"someValue\"}"
auction_signals: "{\"testKey\":\"someValue\"}"
scoring_signals: "{\"renderUrls\":{\"https://localhost:5003/ad.html\":[1,2,3],\"https://localhost:5004/ad.html\":[1,2,3]}}"
publisher_hostname: "localhost"
enable_debug_reporting: true
log_context {
  generation_id: "c2824bfc-d515-4a1a-9de9-7660ad963252"
}
per_buyer_signals {
  key: "https://localhost:5003"
  value: "{\"testKey\": \"someValue\"}"
}
per_buyer_signals {
  key: "https://localhost:5004"
  value: "{\"testKey\": \"someValue\"}"
}
seller: "https://localhost:6002"

4.3.6 Resposta ScoreAds do serviço de leilão

O serviço de leilão do vendedor responde com a pontuação de conveniência:

I1210 21:20:47.298029      33 default_async_grpc_client.h:134] Decrypting the response ...
I1210 21:20:47.298100      33 default_async_grpc_client.h:152] Decryption/decoding of response succeeded: ad_score {
  desirability: 9
  render: "https://localhost:5003/ad.html"
  interest_group_name: "dsp-x-demo"
  buyer_bid: 9
  interest_group_owner: "https://localhost:5003"
  win_reporting_urls {
    top_level_seller_reporting_urls {
    }
  }
  ad_type: AD_TYPE_PROTECTED_AUDIENCE_AD
}

4.3.7 Resposta SelectAd da SFE

A resposta SelectAd do SFE é criptografada e enviada para o SAS:

I1210 21:20:47.298428      33 select_ad_reactor.cc:1413]  (generationId: c2824bfc-d515-4a1a-9de9-7660ad963252) Encrypted SelectAdResponse:
auction_result_ciphertext: "\023\233\252\321\000\331M\327\216\201S\332kl?\322\255\247\312\375h\007W\367\016\366FR\364\275\377\326\027h\204\203\265\t\271-\333\266\tH\342\033F\001k\211C\026V\013\271\255(\236\273\353\260\275\007\346\027\340?\005|\235S\244\265\2563U\246\322\177%\200/\3175\034 \020\024\362\345\3263\356F.s\261\005\231\262Z\000\330x\0230\335>\"\217\254\010\254\330>\206\007\274\235\037`\370W\032\207\356\367\206\026\341.i\"$\370\367\2554i\247\354\304e\306\2466S\337\321w\327+!\316\035:\002\231\246\362\366qm\211\000\013\343\345\224{\365py\361\374\316\202\217-\244\302\331\216D\025W#.\304nH\235\315\311<#\342\344\324\257\354\2441\251\312\320\226\342\021\377>3`\347/\350\254h\306\273\023\365\340@\321\2412\254\323\213\0137,\013n\220|\211\323/\030)\314\263\223\355>\254\312aa`!\375\335\023Z\234p\206\037\001\355\261{$\025+\341\275\327Ny\342\342\264=\376\2138\224\026\2058\251\020\202\245*46\023\307)K\342\364k<\2104r\247\034\216}\034\001\374\215\363\210\026\275\371S>\031;f.b\260\363\257.\255\023I\341A\237*_T\355\262\005\344L\336D%\327\267@\302$\300\340\203c\350|\337>C\275c\260\202o\315xp\260\257\241\305U\nK\033\274L6\025\350\373a:\253\212&>p\210\215\017&^\327\005_\037\020\212\362\351\341\231@g\372\0037\275b:)\207\303d\243?\261O\266\343\214\200\004\247\372\022S\326\200\037\330\252r\257+e\273[\231\202\3625{\330\213\240\370\245\\\214\350/\313\ty/\004\313\0304k\223\354\374\305\233\264\224K\344\241\251\322?\323q6\314D\027\200\203\035]\023O\306\230?\203\237:\254\305\265\332\330\2641l\322\020\022\330O-\242\207>Q\364_{F\235\353tk\207\035\205\005\221\373\207\0143\035\014\322\240H\220\347%\262f\347\017\352\273\265\231\014\204\r\312\254z\000\340&\354\222\323\245\356\217(i\246"

5. Testar com o app de teste local no navegador

5.1 Abrir o Chrome

Leia o artigo do Chromium sobre como iniciar o Chrome na linha de comando e faça isso com as seguintes flags:

google-chrome --enable-privacy-sandbox-ads-apis --disable-features=EnforcePrivacySandboxAttestations,FledgeEnforceKAnonymity --enable-features=FledgeBiddingAndAuctionServerAPI,FledgeBiddingAndAuctionServer:FledgeBiddingAndAuctionKeyURL/https%3A%2F%2Fstorage.googleapis.com%2Fba-test-buyer%2Fcoordinator-test-key.json

A flag está definida para carregar a chave do coordenador simulado que hospedamos em https://storage.googleapis.com/ba-test-buyer/coordinator-test-key.json.

Importante: saia completamente de todas as instâncias do Chrome antes de abrir o navegador na linha de comando com as flags de B&A. Para sair de todos os processos do Chrome, execute ps aux | grep -ie chrome/chrome | awk '{print $2}' | xargs kill -9 na linha de comando.

5.2 Acesse a interface do app de teste local

A interface do app pode ser encontrada em http://localhost:3000 na instância do navegador Chrome que você abriu com as flags. O endereço exato que você acessa pode ser diferente se estiver usando uma VM com um nome de host diferente.

Uma captura de tela do app de teste local sendo acessado em um navegador

Na linha superior do app, o painel "Controles" contém os botões para simular diferentes configurações de leilão. Os outros dois painéis contêm iframes dos sites do anunciante e do publisher.

Uma captura de tela dos grupos de interesse no Chrome DevTools.

Em seguida, clique nos botões do painel "Controles" para simular vários tipos de leilão.

Se os Serviços de B&A e o app de teste local estiverem configurados corretamente, o anúncio anterior será renderizado no painel "iframe do site do editor".

5.3 Configuração do leilão do app de teste local

No app complementar de teste local, os seguintes participantes são hospedados, diferenciados pelo número da porta (uma porta diferente é considerada de origem cruzada):

Há quatro DSPs:

• O DSP-A e o DSP-B participam de leilões no dispositivo
• DSP-X e DSP-Y participam de leilões de B&A

Há quatro SSPs, e cada vendedor executa uma configuração de leilão diferente:

• O SSP-OD faz um leilão somente no dispositivo
• SSP-BA faz um leilão somente de B&A
• SSP-MIX faz um leilão de modo misto
• SSP-TOP faz um leilão de vários vendedores
  • SSP-OD/BA/MIX participam como vendedores de componentes do leilão de vários vendedores da SSP-TOP

Para conferir a arquitetura completa, consulte o diagrama de design.

5.4 Configuração dos serviços de lances e leilões

Neste codelab, vamos executar dois conjuntos de B&A lado a lado.

• No conjunto A, os serviços do comprador são usados por DSP-X e os serviços do vendedor são usados por SSP-BA.
• No conjunto B, os serviços do comprador são usados por DSP-Y e os serviços do vendedor são usados por SSP-MIX.

Para a comunicação entre o app de teste local e os serviços do B&A, é usada uma rede de ponte do Docker. A rede de ponte ba-dev é criada pelo script de configuração do app Local Testing. Os serviços de B&A recebem um endereço IP na sub-rede de 192.168.84.0.

Por exemplo, quando você chama o SFE do conjunto A no aplicativo, o endereço de rede de 192.168.84.104:50053 é usado. Ao carregar o script de lances simulados do DSP-X no BFE, https://192.168.84.100:5003/generate-bid.js é usado.

6. Conclusão

Esperamos que você já tenha se familiarizado com a execução da pilha de serviços de B&A localmente na sua máquina e tenha entendido melhor como os serviços se comunicam entre si.

6.1. Suporte técnico

• Se você tiver uma dúvida sobre a configuração do app de teste local, abra um problema no repositório do LTA.
• Se você tiver uma dúvida sobre os serviços de lances e leilões, abra um problema no repositório de serviços de lances e leilões.

6.2 Saiba mais

• Saiba mais sobre a arquitetura de B&A para a Web.
• Saiba mais sobre a integração do vendedor com a B&A para a Web.