建立回應

應用程式處理 Google 的出價要求後,必須建立並傳送回應。本指南說明如何編寫應用程式程式碼來建構回應。

建立 Protobuf BidResponse 訊息

Authorized Buyers 會將 BidRequest 傳送為 HTTP POST 的訊息主體。如果出價端點已設定為使用 Protobuf 格式,應用程式必須傳送回應,其中 Content-Type 標頭設為 application/octet-stream,而訊息主體則包含序列化的通訊協定緩衝區。通訊協定緩衝區是 BidResponse 訊息,如 openrtb.proto 所定義。應用程式必須針對每個 BidRequest 傳回可剖析的 BidResponse。逾時和無法剖析的回應會視為錯誤,Google 會限制錯誤率過高的出價方。

如果您不想對曝光出價,則必須傳回空白的 HTTP 204 回應。您可以從「參考資料」頁面取得 openrtb.proto

廣告素材 ID

您的 BidResponse 會透過 BidResponse.seatbid.bid.crid 欄位指定廣告素材 (上限為 64 個位元組)。即使是相似的廣告素材,如果在任何顯著特徵上有所差異,也必須為這個欄位提供不重複的值,包括但不限於尺寸、宣告的網址、廣告素材屬性和供應商類型。換句話說,您必須為任何兩則廣告提供不同的廣告素材 ID,前提是:

  • 外觀或行為有所不同。
  • 算繪至不同的圖片。
  • 以不同的方式算繪 (例如,一個廣告包含圖片,另一個則是影片)。

設計應用程式時,您應決定以系統化方式產生 ID,以便針對您要提交的廣告素材類型產生適當的 ID。

廣告屬性

Google 建議您宣告廣告素材屬性,以便描述廣告的特性和指定目標,方法是使用 BidResponse.seatbid.bid.apisBidResponse.seatbid.bid.attr 的組合,或是 BidResponse.seatbid.bid.ext.attribute 擴充功能。以下說明如何宣告屬性:

  • VPAID
    BidResponse.seatbid.bid.apis 設為 VPAID_1VPAID_2。對於 JSON 格式,您可以分別將其設為 12
  • MRAID
    BidResponse.seatbid.bid.apis 設為 MRAID_1,或將 3 設為 JSON 格式。
  • SIZELESS
    BidResponse.seatbid.bid.attr 設為 RESPONSIVE,或 18 為 JSON 格式。
  • PLAYABLE
    如要表示這項資訊,請將 BidResponse.seatbid.bid.attr 設為 USER_INTERACTIVE,或將 13 設為 JSON 格式。

請參閱廣告素材資源,瞭解如何取得廣告素材偵測屬性的意見回饋。

公開出價欄位

參與公開出價的廣告交易平台和聯播網出價方傳送的出價回應,與參與標準即時出價的授權買方傳送的出價回應類似。公開出價客戶可以指定少數額外欄位,而部分現有欄位可能有其他用途。其中包括:

OpenRTB Authorized Buyers 詳細資料
BidResponse.imp[].pmp.deals[].id BidResponse.ad[].adslot[].exchange_deal_id

廣告交易 ID 來自廣告交易平台的命名空間,與此出價相關聯,並回報給發布商。

BidResponse.seatbid[].bid[].ext.exchange_deal_type BidResponse.ad[].adslot[].exchange_deal_type

向發布商回報的交易類型,會影響競價中對交易的處理方式。

BidResponse.seatbid[].bid[].ext.third_party_buyer_token BidResponse.ad[].adslot[].third_party_buyer_token 如果廣告交易平台是公開出價方,則此符記可用於識別最終第三方買家資訊。這個值是從第三方買家取得,必須在出價回應中保持不變,才能傳送給 Google。

建議

  • 在伺服器上啟用永久 HTTPS 連線 (也稱為「保持運作」或「重複使用連線」)。將逾時值設為最少 10 秒,在許多情況下,更高的值會更有幫助。Google 會在應用程式的初始延遲時間測試期間驗證這項設定,因為授權買家會以高頻率傳送要求,因此需要避免為每個要求建立個別 TCP 連線的延遲時間開銷。
  • 加入選用的曝光追蹤網址,以便追蹤曝光顯示時的情況,而非出價方勝出時的情況。由於勝出和算繪之間存在落差,因此這麼做可產生更準確的追蹤統計資料。

  • 請確保出價方程式碼不依賴已淘汰的欄位,否則可能導致出價失敗並顯示錯誤。
  • BidResponse 中加入 BidResponse.seatbid.bid.wBidResponse.seatbid.bid.h。請注意,如果請求包含多個廣告尺寸,BidResponse 必須包含這些欄位,否則會從競價中移除。
  • 回應大小不得超過 8K。回應內容過大可能會增加網路延遲時間,並導致逾時。
  • 請遵循 iOS 廣告空間出價指南,這些廣告空間需要 SKAdNetwork 歸因資料

出價回應範例

以下範例代表 Protobuf 和 JSON 要求的可讀取範例。

OpenRTB Protobuf

OpenRTB JSON

Google

重要事項:範例中顯示的 Protobuf 訊息,在此處以人類可讀的文字表示。不過,這並不是訊息透過電線傳送的方式。使用 Google 或 OpenRTB Protobuf 格式時,系統只會接受已序列化的 BidResponse 訊息。

您可以使用下列 C++ 程式碼建立及序列化 BidResponse 訊息:

BidResponse bid_response;
// fill in bid response with bid information
string post_response;
if (bid_response.SerializeToString(&post_response)) {
  // respond to the POST with post_response as the content
} else {
  // return an error to the POST
}

指定廣告素材

出價回應會指定在出價勝出時放送的廣告素材。您的出價必須包含支援的廣告格式 (AMP、影片、原生) 之一。在本範例中,我們使用 html_snippet 欄位指定廣告素材。

或者,您也可以根據廣告格式,使用任一下列欄位指定廣告素材:

  • SDK 算繪的廣告
    • BidResponse.seatbid.bid.ext.sdk_rendered_ad
  • AMP
    • BidResponse.seatbid.bid.amp_ad_url
  • 影片
    • BidResponse.seatbid.bid.adm
  • 原生
    • BidResponse.seatbid.bid.adm_native

BidResponse.seatbid.bid.adm 欄位中使用 HTML 程式碼片段,指定在您自有伺服器上託管的廣告。程式碼片段會封裝在插入網頁的 iFrame 中,因此在載入網頁時,系統會擷取並轉譯廣告。您必須編寫 HTML 程式碼片段,讓廣告 (橫幅或插頁式廣告) 正確顯示在 iFrame 中,並以適當大小顯示在您出價的廣告版位中。

此外,在下列情況下,出價回應中宣告的大小必須與出價要求中完全相符的大小組合相符:

  • 廣告是一般橫幅廣告 (不是影片、原生或插頁式廣告)。
  • 出價者已在出價回應中宣告大小。請求中只要有兩種以上的大小,就必須宣告大小。
  • 插頁式廣告則例外。插頁式廣告的寬度必須至少為螢幕寬度的 50%,高度則至少為螢幕高度的 40%。

您可以使用任何有效的 HTML 程式碼指定 HTML 廣告素材片段,但請注意,在「Create BidResponse message」部分指定 crid 欄位時,請遵守相關限制。這項功能的其中一個用途,就是在擷取自伺服器的網址引數中加入額外資訊,以便在算繪廣告時使用。這樣一來,您就能將曝光次數的任意資料傳回至自己的伺服器。

在出價回應中傳回的 HTML 程式碼片段,大多數政策與第三方廣告相同。詳情請參閱「授權買方計畫規範」、「第三方廣告放送相關規定」和「在廣告中宣告點閱率網址」。

指定巨集

巨集是格式化的文字,嵌入含有網址的部分出價回應欄位,系統會在廣告放送期間將巨集替換為相關值。舉例來說,如果您在出價時,HTML 程式碼片段廣告素材中包含得標出價的 AUCTION_PRICE 巨集,系統就會將巨集替換為您可解密的值,以便判斷您在競價中為曝光支付的金額。

您可以在下列欄位中加入巨集:

  • BidResponse.seatbid.bid.adm

    巨集支援 HTML 程式碼片段、原生、影片網址和影片 VAST XML 格式。

  • BidResponse.seatbid.bid.adm_native.eventtrackers.url

  • BidResponse.seatbid.bid.adm_native.imptrackers

  • BidResponse.seatbid.bid.ext.amp_ad_url

    AMP 廣告素材僅支援 Google 專屬的 WINNING_PRICEWINNING_PRICE_ESC 巨集。

  • BidResponse.seatbid.bid.burl

  • BidResponse.seatbid.bid.ext.impression_tracking_url

    如果您需要多個帳單網址,請使用這個值,而非 BidResponse.seatbid.bid.burl

舉例來說,您可以將巨集納入 HTML 程式碼片段,方法是在用於擷取廣告素材的網址中嵌入 ${MACRO},其中 MACROOpenRTB 規格中所述的支援巨集之一。

Google RTB 巨集

除了 OpenRTB 規格中的巨集,Google 也支援其他巨集。這些巨集的格式不同,如果嵌入網址,會顯示為 %%MACRO%%。下表說明這些巨集:

巨集 說明
ADVERTISING_IDENTIFIER 允許買方在曝光呈現時收到 iOS IDFA 或 Android 廣告 ID。詳情請參閱「解密廣告主 ID」。
CACHEBUSTER 隨機的無符號四位元整數字串表示法。
CLICK_URL_UNESC

廣告的未逸出點擊網址。在程式碼片段中,第三方點擊網址的已編碼版本應直接接在巨集後方。

舉例來說,如果第三方點擊網址是 http://my.adserver.com/some/path/handleclick?click=clk,則可在巨集呼叫後,使用單一逸出的第三方點擊網址版本搭配下列程式碼:

<a href="%%CLICK_URL_UNESC%%http%3A%2F%2Fmy.adserver.com%2Fsome%2Fpath%2Fhandleclick%3Fclick%3Dclk"></a>

廣告放送時,會展開為:

<a href="http://google-click-url?...&ad_url=http%3A%2F%2Fmy.adserver.com%2Fsome%2Fpath%2Fhandleclick%3Fclick%3Dclk"></a>

這個網址會先向 Google 註冊點擊,然後重新導向至第三方點擊網址。

CLICK_URL_ESC

廣告的轉義點擊網址。如果您需要先將值傳遞到另一部稍後將會傳回重新導向的伺服器,請使用此巨集取代 CLICK_URL_UNESC

例如,下列程式碼可用於 HTML 程式碼片段:

<a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC%%"></a>

廣告放送時,這會展開為:

<a href="http://my.adserver.com/click?google_click_url=http://google-click- url%3F...%26ad_url%3D"></a>

這會將點擊事件註冊至 my.adserver.com,而 my.adserver.com 會負責將使用者重新導向至 google_click_url 參數中傳遞的網址。這會假設 my.adserver.com 會為 google_click_url 參數解碼。

您可以將雙轉義網址附加到 %%CLICK_URL_ESC%% 之後。my.adserver.com 完成解碼後,會將單一逸出的網址版本附加到 google_click_url。擷取 google_click_url 時,系統會再次解碼,然後重新導向。

CLICK_URL_ESC_ESC

廣告的雙逸出網址。如果您需要先將值傳遞到另一部稍後將會傳回重新導向的伺服器,請使用此巨集取代 CLICK_URL_UNESC

例如,下列程式碼可用於 HTML 程式碼片段:

<a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC_ESC%%"></a>

廣告放送時,這會展開為:

<a href="http://my.otheradserver.com/click?google_click_url=http%3A%2F%2Fmy.adserver.com%2Fclick%3Fgoogle_click_url%3Dhttp%3A%2F%2Fgoogle-click-%20url%253F...%2526ad_url%253D"></a>
SCHEME 如果出價要求不要求 SSL,則會展開為 http:;如果出價要求要求 SSL,則會展開為 https:
SITE 內容網址的網址逸出網域,或匿名廣告空間的匿名 ID。
SITE_URL 已淘汰,已由 SITE 巨集取代,後者提供相同的功能。
TZ_OFFSET 時區偏移。
VERIFICATION

製作時和廣告素材在驗證管道中掃描時的不同值。格式如下:%%?VERIFICATION:true-val:false-val%%,其中除了巨集以外的任何值都可以用於 true-valfalse-val,包括空白字串。針對公開出價,我們建議廣告交易平台使用這個巨集;一旦廣告交易平台使用這個巨集,需求方平台就不需要進行變更。

舉例來說,如果廣告素材包含 %%?VERIFICATION:-1:5000%%,則文字替換會在放送時為 5000,在驗證管道中為 -1。這有助於區分這兩組 ping。

WINNING_PRICE

經過編碼的曝光費用 (單次安裝出價,而非千次曝光出價),以帳戶幣別的百萬分之一表示。舉例來說,以美金 $5 元贏得的千次曝光出價,相當於 5 百萬個百萬分之一的千次曝光出價,或是 5 千個百萬分之一單次安裝出價。在此情況下,WINNING_PRICE 的解碼值為 5,000。單次安裝出價中會指定勝出價格。

如要剖析這個巨集,您必須導入可解密價格確認的應用程式。詳情請參閱「解密價格確認資料」頁面。

WINNING_PRICE_ESC 網址逸出的 WINNING_PRICE

Google 規定您必須在第三方放送廣告的廣告素材中使用 CLICK_URL_UNESCCLICK_URL_ESC 巨集。Google 會使用 CLICK_URL 巨集追蹤點擊次數。

巨集中的網址逸出會使用以下配置:

  • 空格字元會由加號 (+) 取代。
  • 英數字元 (0-9、a-z、A-Z) 和 !()*,-./:_~ 集合的字元則保持不變。
  • 所有其他字元都會替換成 %XX,其中 XX 是代表字元的十六進制數字。

發布商限制和規定

出價要求包含資訊,說明發布商在競價中對廣告素材設定的限制類型和要求。

  • BidRequest.bcat
    • 您可以比較這個欄位指定的封鎖類別,以及使用即時出價 API 的 detectedCategories 欄位,為提交的廣告素材偵測到的類別。
  • BidRequest.imp.ext.allowed_vendor_type
  • BidRequest.imp.secure
    • 實際上,這項屬性一律會設為 true,因為 Google 要求所有廣告素材都支援 SSL。
  • BidRequest.imp.{audio/banner/native/video}
  • BidRequest.imp.{audio/banner/native/video}.api
  • BidRequest.imp.{audio/banner/native/video}.battr
  • BidRequest.imp.{audio/banner/video}.mimes

請勿使用含有受限功能的廣告出價。如果是允許的功能 (例如供應商類型),只有在廣告供應商類型出現在 BidRequestallowed_vendor_type 清單中的情況下,您才需要傳回廣告。出價中應只包含出價要求中指定的廣告格式,也就是填入 BidRequest.imp.banner 等欄位。如需詳細資訊,請參閱 BidRequest 通訊協定緩衝區定義中這些欄位的註解。

如果廣告在 BidResponse 中傳回,您必須在 BidResponse 中正確設定 BidResponse.seatbid.bid.attrBidResponse.seatbid.bid.cat,以及 BidResponse.seatbid.bid.adomainBidResponse.seatbid.bid.adm_native.link.url 欄位。如果廣告對這些欄位有許多適用的值,則必須納入每個值。如需更多詳細資訊,請參閱 BidResponse 通訊協定緩衝區定義中這些欄位的註解。系統會捨棄未設定這些欄位的回應。

Open Measurement

您可以透過 Open Measurement 指定第三方供應商,為放送至行動應用程式環境的廣告提供獨立評估和驗證服務。

支援的廣告格式包括影片、橫幅和插頁式廣告。如要進一步瞭解如何在包含這些格式的出價回應中使用 Open Measurement,請參閱 Open Measurement SDK 說明中心文章。

出價回應範例

下列各節會列出不同廣告類型的範例出價回應。

應用程式橫幅廣告

OpenRTB Protobuf

OpenRTB JSON

Google

應用程式插頁式廣告

OpenRTB Protobuf

OpenRTB JSON

Google

應用程式插頁式影片

OpenRTB Protobuf

OpenRTB JSON

Google

原生應用程式

OpenRTB Protobuf

OpenRTB JSON

Google

網路影片

OpenRTB Protobuf

OpenRTB JSON

Google

廣告交易平台出價方適用的行動版網站橫幅廣告

OpenRTB Protobuf

OpenRTB JSON