使用 Ad Placement API

Ad Placement API 包含兩個函式：adBreak() 和 adConfig()，定義於下列全域命名空間。大多數引數都是您提供的函式，可讓您處理準備及顯示廣告的關鍵步驟：

adBreak({
   type: '<type>',                      // The type of this placement
   name: '<name>',                      // A descriptive name for this placement
   beforeAd: () => {},                  // Prepare for the ad. Mute and pause the game flow
   afterAd: () => {},                   // Resume the game and un-mute the sound
   beforeReward: (showAdFn) => {},      // Show reward prompt (call showAdFn() if clicked)
   adDismissed: () => {},               // Player dismissed the ad before completion
   adViewed: () => {},                  // Ad was viewed and closed
   adBreakDone: (placementInfo) => {},  // Always called (if provided) even if an ad didn't show
});

adConfig({
   preloadAdBreaks: 'on|auto',      // Should ads always be preloaded
   sound: 'on|off',                 // Is sound currently enabled within the game
});

這些函式用於在遊戲中放送及設定廣告。上述引數是唯一可傳遞至這些函式的有效引數。不同類型的廣告需要不同的引數子集，詳情如下。

adBreak() 是在遊戲中放送廣告的關鍵函式。它會定義廣告刊登位置，並採用名為「刊登位置設定」的物件，指定顯示廣告所需的一切資訊。

adBreak() 函式會定義廣告可能顯示的刊登位置。 廣告是否實際顯示取決於下列因素：

  • 您聲明的廣告刊登位置類型
    • 這則廣告是在比賽開始前播放嗎？等級之間？在玩家暫停遊戲時？
  • 目前播放器是否有合適的廣告
    • 這則廣告是否與他們有關聯？
    • 是否與他們的資料隱私權和同意聲明設定一致？
  • 播放器最近看過的廣告數量
  • 您為這款遊戲設定的控制項設定，例如廣告展示頻率
    • 可做為代碼中的提示，或
    • 在 AdSense 中，請注意，AdSense 中提供的控制項會隨著時間演進。

顯示的廣告類型也取決於類似因素。

請注意，呼叫 adBreak() 可能完全不會顯示廣告。只是宣告廣告「可能」顯示的位置。

這與傳統 API 不同，在傳統 API 中，您的程式碼一律會知道是否有可用的廣告，並由您在遊戲中決定是否顯示廣告。這種做法是讓 Ad Placement API 決定是否在特定刊登位置顯示廣告，有時也稱為「控制反轉」模式。

我們將遊戲 API 轉換為這種模式的原因，首先是為了縮短您必須在遊戲中編寫的程式碼。其次，這項功能可讓您更輕鬆地提供符合政策的刊登位置，同時提供優質的使用者體驗，進而讓我們向遊戲發布商提供一些成效最高的格式。最後，這樣做可更清楚地將在遊戲中放送廣告的程序，與要顯示的廣告類型和數量等營利決策分開。

我們希望您不必編輯及發布新版遊戲，就能變更營利設定及控管使用者體驗，因此一開始會先在標記中指定提示。但日後推出的版本中，我們將直接在 AdSense 和 AdMob 前端提供控制項。

插頁式廣告

插頁式廣告為全螢幕廣告，可在遊戲中的不同時間點顯示，例如玩家開始遊戲時，或完成關卡後。系統會暫停遊戲，並在整個文件中顯示廣告，玩家可以選擇點按廣告 (廣告會顯示在瀏覽器的另一個分頁中)，或是關閉廣告並繼續遊戲。

如要放送插頁式廣告，請在刊登位置設定中填入下列欄位：

adBreak({
   type: 'start',           // The type of this placement
   name: 'game_started',    // A descriptive name for this placement
   beforeAd: beforeAd,      // Prepare for the ad. Mute and pause the game flow
   afterAd: afterAd,        // Resume the game and un-mute the sound
   adBreakDone: breakDone,  // Always called (if provided) even if an ad didn't show
});

type 引數為必填，建議您一律為刊登位置命名。其他回呼函式則為選用。

通話序列

查看插頁式廣告的呼叫順序。

插頁式廣告呼叫序列圖

說明

插頁式廣告 - 詳細呼叫順序
您的 H5 遊戲 Ad Placement API
  初始化和預先載入廣告
執行遊戲  

放送廣告的好時機...

adBreak() →

 
 

有可用的廣告，現在是顯示廣告的好時機...

← beforeAd()
遊戲會暫停、靜音，並準備顯示廣告。

return 至 API →

 
  Ad Placement API 會算繪插頁式廣告。玩家可以點按廣告 (廣告會顯示在新分頁中)。他們必須關閉廣告才能繼續玩遊戲。
  ← afterAd() is called if an ad has been shown
遊戲會取消暫停並取消靜音。  
  ← adBreakDone()一律會呼叫 adBreakDone() (即使未顯示廣告)
遊戲會記錄這個刊登位置的分析資料。  

附註

  • adBreak() 是會立即傳回內容的非同步函式。
  • 如果刊登位置沒有可顯示的廣告，系統就不會呼叫任何回呼，也就是不會呼叫 beforeAd() 和 afterAd()。
  • 為確保遊戲不會在顯示廣告時繼續執行，請使用 beforeAd() 回呼靜音並暫停遊戲。
  • beforeAd() 是同步的，因此 Ad Placement API 會等到傳回值後，才顯示廣告。
  • 接到 afterAd() 電話時，請重新啟動遊戲並取消靜音。
  • 如果提供 adBreakDone()，即使這個刊登位置未顯示廣告，系統一律會呼叫 adBreakDone()。
  • 如果另一個廣告正在顯示，呼叫 adBreak() 會失敗，且 JavaScript 控制台會顯示警告。

片頭廣告

片頭廣告是插頁式廣告，會在遊戲載入使用者介面前顯示。這是玩家瀏覽遊戲時最先看到的內容，由於前置廣告會在網頁載入的早期階段播放，且遊戲尚未顯示，因此不需要一般的暫停和靜音遊戲呼叫。而是使用 adBreakDone() 回呼，依序啟動遊戲和廣告，也就是算繪 UI 並開始播放音效。每次網頁載入時，只能觸發一個前置廣告。

通話序列

系統會在網頁載入初期呼叫前置廣告。由於遊戲此時尚未算繪 UI，因此您不應傳遞 beforeAd() 和 afterAd() 回呼。請改用 adBreakDone() 回呼在刊登位置後啟動遊戲，因為即使沒有廣告，系統也保證會呼叫這個回呼。

片頭廣告呼叫順序圖

在遊戲邏輯中盡早呼叫下列程式碼，即可放送前置廣告。 呼叫此程式碼前，不應算繪 UI。

// Game must not be running.
// Nothing in the game area should be clickable
adBreak({
   type: ‘preroll',
   adBreakDone: startGame,
})
前置廣告 - 詳細的呼叫順序
您的 H5 遊戲 Ad Placement API
  API 初始化和廣告預先快取作業開始
正在執行，但尚未啟動，且未顯示 UI  

adBreak(type:'preroll',…) →

 
 

Ad Placement API 完成初始化並載入廣告。如有廣告，系統就會顯示。玩家可以點按廣告 (廣告會顯示在新分頁中)。他們必須關閉這則訊息，遊戲才會開始。

 

← adBreakDone() 一律會呼叫 (即使未顯示廣告)

遊戲 UI 會顯示在畫面上，玩家現在可以與其互動。遊戲可以視需要使用傳遞至 adBreakDone() 的 placementInfo 物件 (例如記錄其他數據分析資料)。

  

附註

  • 前置廣告一律會嘗試預先載入廣告：
    • 前置片頭不需要呼叫 adConfig(preloadAds: ‘on')。
  • 與其他廣告刊登位置一樣，前置片頭廣告可能會顯示廣告，也可能不會。
  • 請勿將 beforeAd() 和 afterAd() 傳遞至前置廣告。
    • 由於片頭廣告會在遊戲開始前放送，因此不需要暫停或將遊戲音效設為靜音。
    • 如果使用前置廣告傳遞 beforeAd() 或 afterAd()，呼叫作業會失敗，且 JavaScript 控制台會記錄錯誤。
  • 片頭廣告會自動等待 Ad Placement API 初始化，並預先載入廣告：
    • 不過，系統會設定逾時時間 (2 秒)，避免呼叫無限期延遲。這樣可確保 adBreakDone() 會及時呼叫，並啟動遊戲。
    • 即使沒有廣告，系統一律會呼叫 adBreakDone()。
  • 建議您使用前置廣告，在遊戲開始前放送廣告。
    • 或者，您也可以使用 onReady() 回呼，將遊戲邏輯與 API 初始化和預先載入廣告的機制排序。adConfig()

獎勵廣告

獎勵廣告可讓玩家選擇觀看廣告，並獲得應用程式內商品做為獎勵。插頁式廣告是選擇停用，玩家會看到廣告，並可選擇關閉。獎勵廣告屬於選擇加入型廣告。玩家可自行選擇是否要觀看廣告來獲得獎勵，以及觀看時間。

與插頁式廣告不同，玩家隨時可以關閉獎勵影片廣告，但必須觀看廣告一段時間 (視顯示的廣告素材而定)，才能獲得獎勵。

由於獎勵廣告是玩家可自由選擇的廣告，因此需要更深入地整合到遊戲流程中。您必須提供相關函式，在遊戲中顯示獎勵提示，並在玩家觀看廣告後發放獎勵。

獎勵不得在應用程式外具有價值，不得具有 (或可輕易兌換成) 貨幣價值，也不得出售或兌換成商品和服務，且您不應鼓勵玩家點按廣告。詳情請參閱插頁式和買家可選擇觀看的廣告草案政策。

由於獎勵是玩家可自由選擇是否要領取的項目，因此您可以在遊戲中任何適當的位置加入獎勵，並搭配中繼插頁廣告使用。與插頁式廣告一樣，這些版位是顯示獎勵廣告的機會。 只有在遊戲中的特定時間點實際提供獎勵廣告時，廣告刊登 API 才會呼叫您的程式碼。

再次強調，我們的目標是讓您整合遊戲與 Ad Placement API 後，就能透過代碼或 AdSense 中的控制項，隨時變更啟用的廣告組合，不必重新編碼及發布遊戲。

有獎廣告空間的類型一律為 'reward'，且可使用廣告空間設定中的所有欄位。

adBreak({
   type: 'reward',                      // The type of this placement
   name: '<name>',                      // A descriptive name for this placement
   beforeAd: () => {},                  // Prepare for the ad. Mute and pause the game flow
   afterAd: () => {},                   // Resume the game and re-enable sound
   beforeReward: (showAdFn) => {},      // Show reward prompt (call showAdFn() if clicked)
   adDismissed: () => {},               // Player dismissed the ad before it finished.
   adViewed: () => {},                  // Player watched the ad–give them the reward.
   adBreakDone: (placementInfo) => {},  // Always called (if provided) even if an ad didn't show
});

主要的新函式包括 beforeReward() (觸發程序，用來發出信號，表示您應顯示獎勵提示) 和 adViewed() (在玩家成功觀看廣告後呼叫，方便您分配獎勵)。

您可以定義的付費刊登位置如下：

adBreak({
   type: 'reward',
   name: 'new_life_reward_1',
   beforeAd: pauseGame,
   afterAd: restartGame,
   beforeReward: showRewardPrompt,
   adDismissed: adDismissed,
   adViewed: adViewed,
   adBreakDone: breakDone,
});

獎勵廣告會先在遊戲中顯示提示，告知玩家觀看廣告可獲得獎勵。

廣告提示範例：觀看影片可獲得額外生命

獎勵廣告的呼叫序列

獎勵通話順序圖

說明

獎勵廣告 - 詳細呼叫序列
您的 H5 遊戲 Ad Placement API
  廣告初始化和預先快取
執行遊戲  

adBreak(type:'reward', ... ) →

 
 

有可用的廣告，因此請開始刊登獎勵廣告。beforeReward() 會同步呼叫，也就是在呼叫 adBreak() 後立即呼叫

← beforeReward(showAdFn)

遊戲會顯示獎勵提示。玩家可藉此觀看廣告來獲得獎勵。您可以提供多種獎勵，例如新的生命或金幣。

玩家可以點選獎勵提示、關閉提示或直接忽略。

如果使用者點選提示，遊戲就會儲存他們要求的獎勵類型，並呼叫 showAdFn()...

否則，如果系統關閉或忽略獎勵提示，就不會發生任何事，直到您再次呼叫 adBreak() 並提供獎勵刊登位置類型為止。屆時，Ad Placement API 會重設並清除這次呼叫的狀態。如果應用程式從先前的廣告插播呼叫 showAdFn，則不會產生任何影響。

  

showAdFn() →

 
  ← beforeAd()

遊戲會暫停、靜音，並準備顯示廣告

return 至 API →

 
  API 會顯示廣告。並提供關閉按鈕，以及廣告剩餘時間的倒數計時。
如果播放器關閉廣告...
  ← adDismissed()
玩家關閉廣告，但遊戲未發放獎勵。  
ELSE the player watches the ad to completion...
  ← adViewed()
玩家看完廣告，遊戲發放獎勵。(這通常是透過設定某些遊戲狀態，然後在遊戲重新啟動時，透過下方對 afterAd() 的呼叫擷取)。  
廣告觀看完畢或遭略過後...
  ← 如果廣告已顯示，系統會呼叫 afterAd()
遊戲會取消暫停並取消靜音。  
  ← adBreakDone()一律會呼叫 adBreakDone() (即使未顯示廣告)
遊戲會記錄這個刊登位置的分析資料。  

附註

  • adBreak() 是會立即傳回內容的非同步函式。
  • 如果刊登位置沒有可顯示的廣告，系統就不會呼叫任何回呼，也就是不會呼叫 beforeAd() 和 beforeReward()。
  • 為確保遊戲不會在顯示廣告時繼續執行，請使用 beforeAd() 回呼靜音並暫停遊戲。
  • beforeAd() 是同步的，因此 Ad Placement API 會等到傳回值後，才顯示廣告。
  • 接到 afterAd() 電話時，請重新啟動遊戲並取消靜音。
  • 如果提供 adBreakDone()，即使這個刊登位置未顯示廣告，系統一律會呼叫 adBreakDone()。
  • 如果另一個廣告正在顯示，呼叫 adBreak() 會失敗，且 JavaScript 控制台會顯示警告。