1. 簡介
出價和競價服務 (B&A) 包含 4 項服務,可協助買方和賣方進行 Protected Audience 競價:
買方堆疊:
- 買方前端服務
- 出價服務
賣方堆疊:
- 賣家前端服務
- 競價服務
本程式碼研究室將引導您逐步完成在本機環境中設定及測試端對端設定。這項操作手冊預計需要 1 小時的時間,不含初始服務建構時間。
即使您只處理買方程式碼或賣方程式碼,在本機環境中設定完整工作流程也很有幫助,這樣您就能更瞭解買方和賣方堆疊如何相互運作。設定這兩個堆疊後,日後整合其他方的買方或賣方堆疊時,您就能更有信心。在本機測試服務也可以節省開發成本。
在本程式碼研究室中,我們會使用 B&A 本機測試應用程式做為逐步操作說明的輔助工具。
隨附的本機測試應用程式會代管在 B&A 競價中使用的各種買家和賣家資源。應用程式也會在 http://localhost:3000
提供 UI,讓您模擬各種競價設定。
2. 環境設定
2.1 準備 Linux 電腦
使用本機 Linux 機器,或佈建您選擇的雲端服務供應商的 Linux VM。為縮短建構時間,建議至少使用 16 個核心,建議使用 32 個以上核心。
請注意,我們會從這個機器的 http://localhost:3000
載入 HTML 頁面。如果 VM 未提供 GUI,請確認您的本機可存取 3000
通訊埠,以便連線。
2.2 安裝 Docker
我們使用 Docker 執行服務和本機測試應用程式。
我們會使用便利指令碼,在測試環境中安裝 Docker。
# 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
警告:在無須使用 sudo 的設定中,Docker 群組會將 root 層級權限授予使用者。詳情請參閱無需使用 sudo 的 Docker 指南。
2.3 啟動隨附的本機測試應用程式
隨附應用程式提供的資源包括模擬出價/評分指令碼,以及模擬 K/V BYOS 端點。應用程式應在執行 B&A 服務之前啟動,以便將資源載入服務。
git clone https://github.com/privacysandbox/bidding-auction-local-testing-app.git
在存放區的根目錄中執行設定指令碼:
./setup
設定指令碼會建立 ba-dev
Docker 網路、產生 SSL 憑證,並建構測試應用程式映像檔。
建構作業完成後,請執行啟動指令碼:
./start
3. 在本機上建構及執行 B&A
3.1 下載 B&A 服務
我們會在同一台電腦上執行兩組 B&A 服務,因此會將存放區拉至兩個不同的資料夾。
組 A:
下載 B&A 存放區:
git clone https://github.com/privacysandbox/bidding-auction-servers.git bidding-auction-servers-set-a
集合 B
下載 B&A 存放區:
git clone https://github.com/privacysandbox/bidding-auction-servers.git bidding-auction-servers-set-b
`
3.2 建構服務
在每個 B&A 資料夾的根目錄中,執行下列指令來建構所有 4 項服務:
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
上述指令會為所有 4 項服務的 Google Cloud Platform (gcp
) 建構開發版本 (non_prod
) 的 local
例項。視需要將 --platform
標記更新為您選擇的雲端服務供應商。如要進一步瞭解建構標記,請查看 build_and_test_all_docker
檔案。
如果使用 64 核心機器,初始建構作業可能需要 2 小時,且建構時間會隨著核心數量線性增加。如果您使用的是 32 核心機器,可能需要 4 小時。如果您使用的是 16 核心機器,可能需要 8 小時。
請注意,後續的建構作業會使用快取,且每個建構作業大約需要 5 到 20 分鐘。
(我在編寫本程式碼研究室時遇到 xkcd 的 Randall Munroe,並告訴他我在這裡加入了這則漫畫)
3.3 執行服務
在測試期間,我們會執行 8 項服務 (每個堆疊 4 項服務)。每個指令都會設定為使用本機測試應用程式提供的資源。強烈建議您使用 tmux
等視窗管理員。
開啟至少 8 個額外的終端機視窗,並在每個工作階段中執行下列指令。
請注意,本機測試應用程式伺服器必須已在個別程序中執行,因為出價和評分指令碼會由應用程式提供。
3.3.1 集 A 指令
服務 | 指令 |
|
|
|
|
|
|
|
|
3.3.2 設定 B 指令
服務 | 指令 |
|
|
|
|
|
|
|
|
3.3.2 本機啟動指令碼的環境變數
您可以使用下列環境變數控制啟動行為。
Env var | 可用性 | 說明 |
| 所有服務 | 為 docker 指令設定的標記 |
| 所有服務 | 在本機上進行測試時,您可能需要使用自行簽署的憑證,但這類憑證無法通過 預設值為 |
| 所有服務 | 服務記錄的層級。等級越高,記錄檔就越多。0 為最低,10 為最高。預設值為 |
| 出價服務 | 出價服務的通訊埠。預設值為 |
| 出價服務 | 出價邏輯的網址 |
| 出價服務 | 模型訓練的資料外流 |
| 出價服務 | 出價推論的引數 |
| BFE 服務 | BFE 服務的通訊埠。預設值為 |
| BFE 服務 | 買方的 BYOS K/V 位址 |
| BFE 服務 | 買方的 TEE K/V 位址 |
| BFE 服務 | 買方的出價服務地址 |
| 競價服務 | 競價服務的通訊埠。預設值為 |
| 競價服務 | 評分邏輯網址 |
| 競價服務 | 買家的勝出報表網址 |
| 競價服務 | 買家的勝出報表指令碼 |
| 競價服務 | 買方勝出報表指令碼 (PAS) |
| SFE 服務 | SFE 服務的通訊埠。預設值為 |
| SFE 服務 | 賣家的競價服務地址 |
| SFE 服務 | 賣家的 BYOS K/V 地址 |
| SFE 服務 | 賣家的 TEE K/V 地址 |
| SFE 服務 | 賣家所在地 |
| SFE 服務 | 買家的 BFE 位址 |
4. 透過指令列使用 Secure Invoke 進行測試
4.1 SFE 測試
您也可以使用 B&A Services 套件中提供的Secure Invoke 工具,直接透過指令列呼叫服務。
4.1.2 SFE SelectAd
酬載
以下 JSON 要求已填入 SSP-BA
的單一賣方 B&A 競價設定:
{
"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]"
}
]
}
}
}
}
在 Set A 的 B&A Services 存放區的根資料夾中,將檔案儲存為 sfe-test.json
(B&A 建構指令碼會將存放區根資料夾中的檔案複製到 Docker 映像檔的 /src/workspace
資料夾)。
4.1.2 使用 Secure Invoke 呼叫 SFE
請從 B&A Services 存放區的根資料夾執行下列指令:
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
如果 B&A 堆疊設定正確,您會收到以下成功回應:
{"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 BFE 測試
4.2.1 BFE GetBids
要求
{
"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"
}
將檔案儲存為 bfe-test.json
,並存放在 B&A Services 存放區的根目錄中。
4.2.2 使用安全叫用功能呼叫 BFE
請從 B&A Services 存放區的根資料夾執行下列指令:
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
如果 B&A 堆疊設定正確,BFE 會傳回以下回應:
{"bids":[{"bid":6,"render":"https://localhost:5003/ad.html","interestGroupName":"dsp-x-demo"}],"updateInterestGroupList":{}}
4.3 檢查 SFE 記錄
前往終端機並檢查 SFE 記錄。我們將逐步說明輸出內容中的幾個重要記錄。
4.3.1 SelectAd
要求的加密酬載
在這個 SFE 記錄輸出中,我們找到 navigator.getInterestGroupAdAuctionData()
呼叫的加密酬載。這個酬載是由瀏覽器產生,並從代碼傳送至 SAS,然後 SAS 會將其轉送至 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 已解密的酬載
在這個輸出內容中,我們找到 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 向 BFE 提出 GetBids
要求
GetBids
要求會從 SFE 傳送至 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 BFE 的 GetBids
回應
BFE 會回應出價:
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 ScoreAds
對競價服務提出要求
收到出價後,SFE 會針對每筆出價向競價服務發出 ScoreAds
呼叫:
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 ScoreAds
競價服務的回應
賣方的競價服務會傳回可取代分數:
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 SelectAd
回應 (來自 SFE)
SFE 的 SelectAd
回應會經過加密,並傳送至 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. 透過瀏覽器使用本機測試應用程式進行測試
5.1 開啟 Chrome
請參閱 Chromium 文章,瞭解如何從命令列啟動 Chrome,並使用下列標記啟動 Chrome:
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
旗標已設為載入我們在 https://storage.googleapis.com/ba-test-buyer/coordinator-test-key.json
上代管的模擬協調器鍵
重要事項:請務必先完全退出所有 Chrome 例項,再透過命令列使用 B&A 標記開啟 Chrome。如要結束所有 Chrome 程序,請嘗試透過指令列執行 ps aux | grep -ie chrome/chrome | awk '{print $2}' | xargs kill -9
。
5.2 前往本機測試應用程式 UI
在您使用標記開啟的 Chrome 瀏覽器例項中,可在 http://localhost:3000 找到應用程式 UI。如果您使用的是具有不同主機名稱的 VM,您造訪的確切網址可能會有所不同。
在應用程式的頂端資料列中,「控制項」面板包含用於模擬不同競價設定的按鈕。其他兩個面板則包含廣告主和發布商網站的 iframe。
當您在廣告主網頁 iframe 中按一下「Load DSP tags」(載入 DSP 代碼) 按鈕時,每個 DSP 的程式碼就會加入網頁。這些指令碼會將使用者加入興趣群組。開啟 Chrome 開發人員工具,然後前往「應用程式 / 儲存空間 / 興趣群組」,查看由 DSP 標記加入的興趣群組:
接著,按一下「控制項」面板中的按鈕,模擬各種競價類型。
如果 B&A 服務和本機測試應用程式設定正確,上述廣告就會在「發布商網站 iframe」面板中顯示。
5.3 本機測試應用程式競價設定
在隨附的本機測試應用程式中,系統會託管下列參與者,並以通訊埠號碼進行區分 (不同的通訊埠視為跨來源):
參與者 | 說明 | 通訊埠 |
廣告主 | 在網頁上載入 DSP 代碼 |
|
發布商 | 在網頁上載入 SSP 代碼 |
|
| 裝置端買家 |
|
| 裝置端買家 |
|
| B&A 買家 |
|
| B&A 買家 |
|
| 頂層賣家 |
|
| 僅限裝置的賣家 |
|
| 僅限 B&A 賣家 |
|
| 混合模式賣家 |
|
有四個 DSP:
DSP-A
和DSP-B
參與裝置端競價DSP-X
和DSP-Y
參與 B&A 競價
共有四個 SSP,每個賣方都會執行不同的競價設定:
SSP-OD
執行裝置端專屬競價SSP-BA
執行僅限 B&A 的競價SSP-MIX
執行混合模式競價SSP-TOP
執行多賣方競價SSP-OD/BA/MIX
以元件賣家的身分參與SSP-TOP
的多賣方競價
如需完整架構,請查看設計圖表。
5.4 出價和競價服務設定
在本程式碼研究室中,我們會同時執行兩組 B&A。
設定 | 服務 | 參與者 |
|
集合 A | 出價服務 |
|
|
BFE 服務 |
|
| |
競價服務 |
|
| |
SFE 服務 |
|
| |
集合 B | 出價服務 |
|
|
BFE 服務 |
|
| |
競價服務 |
|
| |
SFE 服務 |
|
| |
應用程式 | 本機測試應用程式 | 全部 |
|
- 在 A 組中,
DSP-X
會使用買方服務,SSP-BA
會使用賣方服務 - 在 B 組中,
DSP-Y
會使用買方服務,SSP-MIX
會使用賣方服務
為在本機測試應用程式和 B&A 服務之間進行通訊,我們使用了 Docker 橋接網路。ba-dev
橋接網路是由本地測試應用程式的設定指令碼建立。B&A 服務會指派 192.168.84.0
子網路中的 IP 位址。
舉例來說,如果您從應用程式呼叫 Set A 的 SFE,系統會使用 192.168.84.104:50053
的網路位址。將 DSP-X 的模擬出價指令碼載入 BFE 時,系統會使用 https://192.168.84.100:5003/generate-bid.js
。
6. 總結
希望您到目前為止,都已熟悉如何在本機上執行 B&A Services 堆疊,並進一步瞭解各項服務之間的通訊方式。
6.1. 技術支援
- 如果您對設定 Local Testing App 有任何疑問,請在 LTA 存放區中提出問題。
- 如果您對出價與競價服務有任何疑問,請在 B&A Services 存放區中提出問題。
- 如果您對 Privacy Sandbox 有任何疑問,請在 privacy-sandbox-dev-support 存放區中提出問題。
6.2 瞭解詳情
- 進一步瞭解 網站的出價和競價架構
- 進一步瞭解賣方與 B&A for web 的整合