建立回應

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

建立 Protobuf BidResponse 訊息

Authorized Buyers 會傳遞 BidRequest 做為 HTTP POST。如果出價端點已設為使用 Protobuf 格式,那麼應用程式必須使用 Content-Type 標頭已設為「application/octet-stream」 以及訊息主體,並由序列化通訊協定緩衝區組成。通訊協定 緩衝區是 BidResponse 訊息,定義如下: openrtb.proto。您的應用程式必須傳回可剖析的 BidResponse 以回應每個 BidRequest。逾時和無法剖析的回應會視為錯誤,Google 會限制錯誤率過高的出價方。

如果不想要對曝光出價 單獨選取「BidResponse.ext.processing_time_ms」欄位 其他欄位空白。您可以從「參考資料」頁面取得 openrtb.proto

廣告素材 ID

您的 BidResponse 會透過 BidResponse.seatbid.bid.crid 欄位指定廣告素材 (上限為 64 個位元組)。同等 如果廣告素材有不同的 任何重要特徵,包括但不限於大小、宣告的網址 廣告素材屬性和供應商類型換句話說,您必須為任何兩則廣告提供不同的廣告素材 ID,前提是:

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

設計應用程式時,您必須決定 產生適用於您計劃類型的廣告素材 ID 。

廣告屬性

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

  • VPAID
    BidResponse.seatbid.bid.apis 設為 VPAID_1。 或 VPAID_2。如果是 JSON 格式,這個值可設為 12
  • MRAID
    BidResponse.seatbid.bid.apis 設為 MRAID_1,或 3 為 JSON 格式。
  • SIZELESS
    將「BidResponse.seatbid.bid.attr」設為 RESPONSIVE,或 JSON 的 18 格式。
  • PLAYABLE
    方法是設定 BidResponse.seatbid.bid.attr 轉換為 USER_INTERACTIVE,或為 JSON 檔案前往 13 格式。

詳情請參閱 廣告素材資源 ,說明如何取得有關 廣告素材。

公開出價欄位

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

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

Ad Exchange 命名空間與此交易相關聯的交易 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.seatbid.bid.w 和 「BidResponse」中的「BidResponse.seatbid.bid.h」。針對包含多個廣告尺寸的請求,BidResponse 必須包含這些欄位,否則會從競價中移除。
  • 回應大小不得超過 8K。回覆數過大可能導致回覆數增加 網路延遲並造成逾時
  • 請遵循這份指南 對需使用 SKAdNetwork 歸因的 iOS 廣告空間設定出價

出價回應範例

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

OpenRTB Protobuf

OpenRTB JSON

Google

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

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

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% 以及螢幕高度

您可使用任何 可正確顯示,但請注意指定 crid 欄位的 建立 BidResponse 訊息部分。 這項功能的其中一個用途,就是在從伺服器擷取的網址引數中加入額外資訊,以便在算繪廣告時使用。這樣您就能 系統會將曝光的相關任意資料傳回您自己的伺服器。

在出價回應中傳回的 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

廣告的逸出點擊網址。使用此 API 取代 如果需要先將值傳遞到「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 登錄點擊, 接著就必須負責重新導向至 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

經過編碼的曝光費用 (亦即單次安裝出價,而非千次曝光出價), 帳戶幣別的百萬分之一。例如,{0}5 美元的勝出千次曝光出價 相當於 5,000,000 個微量千次曝光出價或 5,000 百萬分之一的單次安裝出價在此情況下,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 通訊協定緩衝區

OpenRTB JSON

Google

應用程式插頁式影片

OpenRTB 通訊協定緩衝區

Google

原生應用程式

OpenRTB Protobuf

OpenRTB JSON

Google

網路影片

Google

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

OpenRTB Protobuf