建立回應

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

建立 BidResponse 訊息

Authorized Buyers 會送出 BidRequest 做為 HTTP POST 的訊息主體。應用程式傳送的回應必須將 Content-Type 標頭設為 application/octet-stream,且訊息內文須由序列化通訊協定緩衝區組成。通訊協定緩衝區是 realtime-bidding.proto 中定義的 BidResponse 訊息。您的應用程式必須傳回可剖析的 BidResponse,以回應每個 BidRequest。無法剖析的逾時和回應將視為錯誤,而 Google 會節制錯誤率偏高的出價工具。

如果您不想要對曝光出價,請單獨設定 processing_time_ms 欄位,並將所有其他欄位留白。您可以從參考資料頁面取得 realtime-bidding.proto

廣告素材 ID

BidResponse 會透過 buyer_creative_id 欄位 (上限為 64 位元組) 指定廣告素材。即使是類似的廣告素材,只要具有任何重要特徵,就必須有不重複的 buyer_creative_id 值 (包括但不限於大小、宣告網址、廣告素材屬性和供應商類型)。換句話說,當任兩個廣告符合以下條件時 就必須指定不同的廣告素材 ID

  • 外觀或行為有所不同。
  • 算繪為其他圖片。
  • 使用不同的方式顯示 (例如,一個廣告包含圖片,另一個廣告包含 Flash)。

在設計應用程式時,您應決定產生 ID 的系統化方法,以便對您打算提交的廣告素材類型決定。

廣告屬性

您必須在 BidResponse.Ad.attribute 中宣告用來描述廣告特性及其指定目標的廣告素材屬性。必須宣告的屬性如下 (另請參閱 buyer-declarable-creative-attributes.txt 中支援屬性的完整清單):

  • 7 Tagging: IsTagged
    廣告包含像素或網路信標,以便針對後續的再行銷活動建立 Cookie ID 清單。
  • 8 Remarketing: IsRemarketing
    廣告會根據 Cookie ID 或裝置 ID 指定消費者,其中 Cookie ID 或裝置 ID 清單代表先前曾與買方所擁有或代表之網站互動的一組消費者。
  • 9 UserInterestTargeting: IsUserInterestTargeted
    廣告會根據 Cookie ID 或裝置 ID 指定消費者,其中 Cookie ID 或裝置 ID 清單代表由買家定義為共同興趣群組的消費群。
  • 30 InstreamVastVideoType: Vpaid
    廣告需要 VPAID 支援才能顯示。
  • 32 MraidType: MRAID
    廣告必須使用 MRAID API 才能顯示。

此外,系統支援下列屬性,但不一定要宣告這些屬性,因為 Authorized Buyers 會自動偵測這些屬性,並會根據偵測到的值 (而非宣告) 封鎖 (或允許) 廣告素材。 如要瞭解如何取得與偵測到的廣告素材屬性相關的意見回饋,請參閱 Creative API

  • 34 RichMediaCapabilityType: RichMediaCapabilityFlash
    廣告需要 Flash 支援才能顯示。
  • 50 RichMediaCapabilityType: RichMediaCapabilityNonFlash
    廣告不需要顯示 Flash 就能顯示。
  • 47 RichMediaCapabilityType: RichMediaCapabilitySSL
    廣告可以顯示在 SSL 網頁上。請注意,Authorized Buyers 會將具有不同此屬性宣告值的廣告素材視為區別 (這些廣告素材會分開審查,且具有不同的核准狀態)。因此,當您對同一廣告素材的 SSL 和非 SSL 版本出價時,應該據此宣告這個屬性,以便在 AdX 中正確反映這項差異。

公開出價欄位

參與公開出價的廣告交易平台和聯播網出價方傳送的出價回應,與參與標準即時出價的 Authorized Buyers 類似。公開出價客戶可以指定少數欄位,並且一些現有欄位可能有替代用途。包括:

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 會在您應用程式的初始延遲測試期間進行這項設定,因為 Authorized Buyers 會以高頻率傳送要求,因此必須避免為每個要求建立個別 TCP 連線造成的延遲時間負擔。
  • 加入選用的曝光追蹤網址,以追蹤曝光顯示的時機 (而非出價工具得標時)。由於勝出和算繪作業之間有落差,可產生更準確的追蹤統計資料。

  • 避免您的出價工具程式碼使用已淘汰的欄位,這可能會導致出價失敗並發生錯誤。
  • BidResponse 中加入 BidResponse.Ad.widthBidResponse.Ad.height。對於包含多個廣告大小的請求,其 BidResponse 必須包含 widthheight 值,否則就會從競價中捨棄。
  • 將回應大小限制在 8K 以下。非常大型的回應可能會增加網路延遲時間,並造成逾時。
  • 遵循需要 SKAdNetwork 歸因功能的 iOS 廣告空間出價指南

出價回應範例

下列範例代表 Protobuf 和 JSON 要求使用者可理解的範例。

Google

OpenRTB JSON

OpenRTB 通訊協定緩衝區

重要事項:範例中顯示的 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.Ad.sdk_rendered_ad
  • AMP
    • BidResponse.Ad.amp_ad_url
  • 影片
    • BidResponse.Ad.video_url
    • BidResponse.Ad.video_vast_xml
  • 原生
    • BidResponse.Ad.native_ad

使用 BidResponsehtml_snippet 欄位中的 HTML 程式碼片段,指定由您自己的伺服器代管的廣告。這段程式碼會包含在插入網頁中的 iframe 中,讓系統在載入網頁時擷取並顯示廣告。您必須製作 HTML 程式碼片段,確保廣告 (橫幅或插頁式廣告) 能在 iframe 中正確顯示,且大小適用於您要出價的廣告版位。

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

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

html_snippet 欄位支援任何可正確顯示的有效 HTML 程式碼,但請留意「建立 BidResponse 訊息」部分中指定 buyer_creative_id 欄位的限制。用於顯示廣告的其中一項用途,是將額外資訊放入網址引數中,系統為了顯示廣告而從伺服器擷取的網址引數。這樣您就能將曝光的任意資料傳回至您自己的伺服器。

在出價回應中傳回的 HTML 程式碼片段,其適用政策與第三方廣告的大多數政策相同。詳情請參閱《Authorized Buyers 計畫規範》、《第三方廣告放送規定》和「在廣告中宣告到達網址」。

指定巨集

定義廣告素材的 HTML 程式碼片段可包含一或多個稱為巨集的特殊結構。在放送廣告時,巨集會被取代值。舉例來說,您的用戶端出價應用程式可以使用 WINNING_PRICE 巨集,決定贏得競價時需為廣告支付的費用。如要剖析這個巨集,您必須實作用來解密價格確認的應用程式。詳情請參閱解密價格確認頁面。

請在 HTML 程式碼片段中以 %%MACRO%% 格式指定巨集,其中 MACRO 是下表支援的其中一個巨集。

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

如要使用巨集,請將其加入廣告,以便在有人點選巨集時擷取網址。擷取的傳回值會重新導向至您附加至 CLICK_URL 的另一個網址。

微距 說明
ADVERTISING_IDENTIFIER 允許買方在曝光顯示時接收 iOS 廣告識別碼或 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 註冊點擊,接著負責重新導向至 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 內容網址的網址逸出網域,或匿名廣告空間的匿名編號。
SITE_URL 已淘汰,已由提供相同功能的 SITE 巨集取代。
TZ_OFFSET 時區偏移。
VERIFICATION 實際工作環境中的值,以及驗證管道中掃描廣告素材的時間。格式為 %%?VERIFICATION:true-val:false-val%%,其中除了巨集以外的任何值都可以用於 true-valfalse-val,包括空字串。針對公開出價,我們建議廣告交易平台使用這個巨集,如果可以,需求端平台就不必進行變更。

舉例來說,如果廣告素材包含 %%?VERIFICATION:-1:5000%%,則在放送時文字替換文字就會是 5000,而驗證管道中的 -1。以利區分這兩組連線偵測 (ping)。
WINNING_PRICE 經過編碼的曝光費用 (即單次安裝出價,而非千次曝光出價),以帳戶幣別的百萬分之一表示。舉例來說,以 $5 美元贏得的千次曝光出價相當於 5,000,000 百萬分之一的千次曝光出價或 5,000 百萬分之一的單次安裝出價。在本例中,WINNING_PRICE 的解碼值為 5,000。得標價格已在單次安裝出價中指定。
WINNING_PRICE_ESC 網址逸出的 WINNING_PRICE

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

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

發佈商限制

發布商會使用 BidRequest 來限制他們允許哪些廣告。您必須強制執行以下欄位中的限制:

  • allowed_vendor_type
  • excluded_attribute
  • excluded_sensitive_category

一個欄位會指定廣告允許的功能,另一個欄位則指定不允許的功能。切勿使用不允許的功能傳回廣告。如果是供應商類型等許可功能,只有當供應商類型在 BidRequestallowed_vendor_type 清單中時,才能傳回廣告。詳情請參閱 BidRequest 通訊協定緩衝區定義中這些欄位的註解。

如果 BidResponse 中傳回 HTML 程式碼片段,請務必正確設定 BidResponse 中的 attributecategoryclick_through_url 欄位。如果廣告針對這些欄位有多個適用的值,您就必須加入所有值。詳情請參閱這些欄位在 BidResponse 通訊協定緩衝區定義中的註解。系統會捨棄未設定這些欄位的回應。

BidRequest.excluded_attribute 的可能值如下 (請參閱 publisher-excludable-creative-attributes.txt):

  • 7 Tagging: IsTagged
    廣告如果包含用於建立 Cookie ID 清單以便後續再行銷的像素或網路信標,則一律禁止。
  • 8 CookieTargeting: IsCookieTargeted
    如果系統根據 Cookie ID 指定消費者,則不允許廣告。這個 Cookie ID 清單代表之前曾與買方所擁有或代表的網站互動的一組消費者。
  • 9 UserInterestTargeting: IsUserInterestTargeted
    假如廣告根據 Cookie ID 指定消費者,則這個 Cookie 清單代表由買家定義為共同興趣群組的消費群,因此不允許廣告。
  • 21 CreativeType: Html
    廣告不得使用 BidResponse.Ad 中的「html_snippet」或「snippet_template」欄位。
  • 22 CreativeType: VastVideo
    廣告不得使用 BidResponse.Ad 中的video_url欄位。
  • 30 InstreamVastVideoType: Vpaid
    系統不允許廣告要求 VPAID 支援才能顯示廣告。
  • 32 MraidType: MRAID
    系統不允許廣告必須使用 MRAID API 顯示。
  • 34 RichMediaCapabilityType: RichMediaCapabilityFlash
    不允許 Flash 支援顯示。
  • 39 RichMediaCapabilityType: RichMediaCapabilityHTML5
    不允許廣告要求 HTML5 功能顯示。
  • 48 RichMediaCapabilityType: RichMediaCapabilityNonSSL
    廣告不得提出非 SSL 請求。

因此,如果 excluded_attribute 欄位包含 7 值,您就不應該傳回使用像素或網路信標建立清單的廣告。請注意,如果廣告這麼做,就必須在 BidResponse 的屬性欄位中設定值 7。同樣地,如果 excluded_attribute 欄位包含 48 值,則應只傳回能在 SSL 網頁上顯示的廣告 (並視情況宣告屬性 47 RichMediaCapabilityType: RichMediaCapabilitySSL)。

此外,BidRequest 中的 excluded_sensitive_category 欄位會使用參考資料頁面上提供的 ad-sensitive-categories.txt 檔案程式碼。以下為其中部分程式碼的延伸說明:

  • 3 Politics
    包含政治或具爭議性社會議題的內容,但不包括整體來說不涉及任何黨派觀點的新聞機構廣告。
  • 4 Dating
    包含交友服務和線上交友社群。
  • 5 Religion
    包含宗教廣告以及宣揚或反對宗教觀點的廣告,但不包含占星術或非宗派靈修類的廣告。
  • 7 Video Games (Casual & Online)
    包含電玩、線上遊戲和可供下載的遊戲,但不包括電玩主機。
  • 8 Ringtones & Downloadables
    鈴聲等行動裝置附加功能以及其他可下載的好康,例如電腦螢幕保護程式和桌布,以及社群網路的個人資料版面配置與圖片。
  • 10 Get Rich Quick
    保證能快速獲得收益的配置。
  • 18 Weight Loss
    包含減重、節食及相關產品和計畫,但不包括健康飲食或一般健身廣告。
  • 19 Cosmetic Procedures & Body Modification
    包含拉皮、抽脂、雷射、除毛和修復、刺青和身體改造。
  • 23 Drugs & Supplements:
    包含藥品、維他命、營養補給品和相關零售商,但不包括提供藥物相關資訊的資源。
  • 24 Sexual & Reproductive Health
    包含性功能和生育能力廣告,但不包含一般懷孕資源。
  • 35 Social Casino Games
    包含無法贏取任何有價物品 (例如獎金或獎品) 的模擬賭博遊戲 (包括但不限於撲克牌、吃角子老虎、賓果、彩券、運動投注、競賽投注,以及其他紙牌遊戲和賭場遊戲)。
  • 36 Significant Skin Exposure
    廣告圖片中有任何從胸骨到大腿中部的人體部分未以衣物遮蔽,或是穿著內衣、泳衣、貼身衣物或其他透明衣物,或是以非衣物 (例如毛巾或床單等) 包覆。
  • 37 Sensationalism
    這類廣告通常會先以誇大用語或圖像引發使用者好奇心,藉此誘導使用者點擊廣告。包含以聳動主題為中心的廣告 (例如名人遭捕、死亡或離婚),或是意圖驚嚇觀眾。

Open Measurement

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

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

出價回應範例

以下各節將顯示不同廣告類型的出價回應範例。

應用程式橫幅廣告

Google

OpenRTB JSON

OpenRTB 通訊協定緩衝區

應用程式插頁式

Google

OpenRTB JSON

OpenRTB 通訊協定緩衝區

應用程式插頁式影片廣告

Google

OpenRTB 通訊協定緩衝區

應用程式原生

Google

OpenRTB JSON

OpenRTB 通訊協定緩衝區

網路影片

Google

廣告交易平台出價工具的行動版網站橫幅廣告

OpenRTB 通訊協定緩衝區