Unity LevelPlay獎勵式廣告串接實戰與教學

最近在串接Unity遊戲的廣告流程，本以為這種事情大家串接經驗都很多，那麼網路上的資源就多，那麼AI的Coding能力就越強。於是乎我就動動嘴皮子，一邊對照著Unity SDK的文件順一下邏輯，在Build APK前的測試都妥妥的，想不到Build出APK後，廣告卻怎麼樣也跑不出來。接著就是苦難的開始···

這是Unity Ad後台的設定頁面，其中的聚合平台的設定。其實嘛，如果串接Google AdMob應該是最快的，資源多、文件的正確率也高，我朋友近期才串接過一次，當天就搞定準備送審了。不過我就想串接看看Unity LevelPlay，或許往後能夠自己依據廣告競價來動態切換聚合平台。

我一開始犯的錯誤使用錯誤的套件：Unity Advertisement，這已經不再更新了。後續AI照個這個套件去把流程刻出來，非常快速且暢快，測試時也都沒問題，然後Build出APK時卻無法正確顯示廣告。

我苦思許久，一度想跳去使用Google AdMob，接著才讓我發現我搞錯套件啦！應該使用的套件是Ads Mediation，並且要到Unity LevelPlay專門的後台去進行廣告單元等等的設定。

使用正確的套件後，原以為馬上就能一帆風順，想不到過程還是跌跌撞撞的，我碰到的問題是：套件調整過命名、新文件內容不齊、部分官方教學未更新...可想而知AI在知識基礎混亂的狀況下，也就常常一派胡言。不過最後還是把基礎的獎勵式廣告的流程處理好了，先來方格子做個筆記，以防我過兩天就腦霧。

版本

我開發的環境及工具羅列如下，供參考：

• IDE
• • Unity 6.2 Beta
  • VS Code
• AD Package
• • Ads Mediation 8.9.0
• AI Tool
• • Gemini CLI
  • ROVO Dev
  • Perplexity

套件安裝

參考官方流程

在 Unity 編輯器中點選上排功能列 Window -> Package Management -> Package Manager -> Unity Registry -> 搜尋Ads Mediation -> Install安裝。

如果安裝上有碰到什麼狀況官方也提供下載unitypackage再import的方式：點我。

後台設定

參考官方流程

在開始Coding前，先到Unity LevelPlay後台創立APP，用Unity的帳號就可以登入了，我的APP因為還沒上架，因此選了下面的選項。

過程中就會問你預計要串接什麼樣的廣告，如果已經規劃好了，就啟用對應的廣告類型。之後在後台也還可以進行設定。

設定完後，在Apps的頁面就能看到你的App Key。選擇APP後，點選Ad units，就能看到各種廣告類型的Ad unit ID。這些資訊記得要從哪邊看，等等會用到。

程式流程

參考初始化官方流程

參考獎勵式廣告官方流程

開始Coding後，就要一邊看文件、一邊抄範例、一邊看IDE有沒有提醒你哪些function已經棄用，並綜合修改。下列我會列出我初步串完獎勵式廣告的版本：

using Unity.Services.LevelPlay;

初始化的流程順序是：

1. 先註冊LevelPlay屆時成功或失敗對應要處理的Function
2. 實例化獎勵式廣告物件，並註冊對應事件要處理的Function
3. 初始化LevelPlay物件

public LevelPlayRewardedAd RewardedAd;

void Start()
{


		LevelPlay.OnInitSuccess += SdkInitializationSuccessEvent;
		LevelPlay.OnInitFailed += SdkInitializationFailedEvent;

		CreateRewardedAd(RewardedAdUnitId);

		LevelPlay.Init(AppKey);

}

private void CreateRewardedAd(string RewardedAdUnitId)

{

	RewardedAd = new LevelPlayRewardedAd(RewardedAdUnitId);
	
	RewardedAd.OnAdLoaded += RewardedOnAdLoadedEvent;
	RewardedAd.OnAdLoadFailed += RewardedOnAdLoadFailedEvent;
	RewardedAd.OnAdDisplayed += RewardedOnAdDisplayedEvent;
	RewardedAd.OnAdDisplayFailed += RewardedOnAdDisplayFailedEvent;
	RewardedAd.OnAdRewarded += RewardedOnAdRewardedEvent;
	RewardedAd.OnAdClosed += RewardedOnAdClosedEvent;

	// Optional
	RewardedAd.OnAdClicked += RewardedOnAdClickedEvent;
	RewardedAd.OnAdInfoChanged += RewardedOnAdInfoChangedEvent;
}

一旦LevelPlay初始化成功後，就可以馬上讓RewardedAd載入廣告

private void SdkInitializationSuccessEvent(LevelPlayConfiguration config)

{

	Debug.Log("LevelPlay SDK 初始化成功！");
	Debug.Log("Ad Quality is " + (config.IsAdQualityEnabled ? "enabled" : "disabled"));

	RewardedAd.LoadAd(); // 載入獎勵式廣告

}

再來就叫AI把獎勵式廣告的Callback Function幫我刻好，我再串接主遊戲流程。其中我開了三個UnityEvent，讓主遊戲流程的模組註冊，分別用來處理：廣告顯示失敗、玩家符合廣告獎勵資格、廣告頁面被關掉的Callback流程。

public UnityEvent OnAdDisplayedFailed; // 廣告顯示失敗時的事件
public UnityEvent OnAdRewarded; // 玩家獲得獎勵時的事件
public UnityEvent OnAdClosed; // 廣告關閉時的事件

然後把AI宣告的空Function補齊

private void RewardedOnAdLoadedEvent(LevelPlayAdInfo adInfo)
{
	Debug.Log("獎勵式廣告載入成功！");
	// 廣告載入成功後可以顯示廣告
	_isRewardedAdLoaded = true; // 更新廣告狀態
}

private void RewardedOnAdLoadFailedEvent(LevelPlayAdError error)
{
	Debug.LogError($"獎勵式廣告載入失敗. 錯誤碼: {error.ErrorCode}, 錯誤訊息: {error.ErrorMessage}");
	// 可以在此處重新嘗試載入廣告
	_isRewardedAdLoaded = false;
	StartCoroutine(RetryLoadRewardedAdCoroutine(5.0f)); // 5秒後重試
}

private void RewardedOnAdDisplayedEvent(LevelPlayAdInfo adInfo)
{
	Debug.Log("獎勵式廣告開始顯示");
	// 廣告開始顯示時的處理邏輯
	_isRewardedAdLoaded = false; // 顯示廣告後，將廣告狀態設為未載入，因為廣告已經被消耗掉了
	RewardedAd.LoadAd(); // 重新載入廣告以便下次使用(最即時的載入時機)
}

private void RewardedOnAdDisplayFailedEvent(LevelPlayAdDisplayInfoError error)
{
	Debug.LogError($"獎勵式廣告顯示失敗. 錯誤碼: {error.LevelPlayError.ErrorCode}, 錯誤訊息: {error.LevelPlayError.ErrorMessage}");
	// 廣告顯示失敗時的處理邏輯
	OnAdDisplayedFailed?.Invoke(); // 通知外部廣告顯示失敗事件
	RewardedAd.LoadAd(); // 重新載入廣告以便下次使用
}

private void RewardedOnAdRewardedEvent(LevelPlayAdInfo adInfo, LevelPlayReward reward)
{
	Debug.Log("玩家獲得獎勵！");
	OnAdRewarded?.Invoke(); // 通知外部玩家獲得獎勵事件
}

private void RewardedOnAdClosedEvent(LevelPlayAdInfo adInfo)
{
	Debug.Log("獎勵式廣告已關閉");
	// 廣告關閉後的處理邏輯，例如重新載入新的廣告
	OnAdClosed?.Invoke(); // 通知外部廣告關閉事件​
}

private void RewardedOnAdClickedEvent(LevelPlayAdInfo adInfo)
{
	Debug.Log("玩家點擊了獎勵式廣告");
	// 廣告被點擊時的處理邏輯
	// 往後加Log分析
}

private void RewardedOnAdInfoChangedEvent(LevelPlayAdInfo adInfo)
{
	Debug.Log("獎勵式廣告資訊已更新");
	// 廣告資訊變更時的處理邏輯
}

private IEnumerator RetryLoadRewardedAdCoroutine(float delay)
{
	// 1. 等待指定的秒數
	Debug.Log($"將在 {delay} 秒後透過協程重試...");
	yield return new WaitForSeconds(delay);
	
	// 2. 等待結束後，執行重試邏輯
	Debug.Log("協程等待結束，開始重試載入廣告。");
	RewardedAd.LoadAd();
}

獎勵式廣告狀態說明

上面的流程有點多有點雜，如果跟我一樣一時之間看不懂，可以參考一下AI老師的解釋：

RewardedAd.OnAdLoaded

• 事件解釋：
  這個事件在廣告成功載入並準備好可以顯示時觸發。這代表 LevelPlay SDK 已經成功從廣告網路下載了廣告素材，並將其儲存在裝置上，隨時等待您的呼叫。
• 該做些什麼？
• 1. 更新廣告狀態：設定一個布林值（例如 isRewardedAdReady = true;），用來記錄廣告已可播放。
  2. 啟用 UI 按鈕：這是最重要的操作。您應該啟用那個「觀看廣告復活」或「領取獎勵」的按鈕，讓玩家可以點擊。例如：watchAdButton.interactable = true;。
  3. 記錄日誌 (Debug)：在開發階段，印出一條日誌 (Debug.Log("獎勵式廣告已載入成功");)，方便您追蹤廣告狀態。

RewardedAd.OnAdLoadFailed

• 事件解釋：
  當 SDK 嘗試載入廣告但失敗時，這個事件會被觸發。失敗的原因多種多樣，可能是網路問題、後台設定錯誤，或是當下沒有可用的廣告（填充率為零）。
• 該做些什麼？
• 1. 更新廣告狀態：設定 isRewardedAdReady = false;。
  2. 禁用 UI 按鈕：確保玩家無法點擊一個不存在的廣告。watchAdButton.interactable = false;。
  3. 錯誤處理與重試：
  4. • 從事件參數中獲取錯誤訊息並印出 (Debug.LogError("獎勵式廣告載入失敗: " + error.Message);)，這對除錯至關重要。
     • 實作重試邏輯。不要立刻重試，這可能會造成伺服器負擔。最佳作法是使用協程 (Coroutine) 或 Invoke，在等待一段時間（例如 5-10 秒）後，再次呼叫 LevelPlay.LoadRewardedAd();。

RewardedAd.OnAdDisplayed

• 事件解釋：
  當您呼叫 LevelPlay.ShowRewardedAd(); 之後，廣告成功地在螢幕上顯示出來時，這個事件會被觸發。
• 該做些什麼？
• 1. 處理遊戲狀態：您可以在此處暫停遊戲（Time.timeScale = 0;），並靜音遊戲背景音樂，以提供更好的廣告觀看體驗。
  2. 更新廣告狀態：將 isRewardedAdReady 設回 false，因為廣告已經被「消耗」掉了。
  3. 預先載入下一則廣告：這是一個非常重要的優化技巧。在廣告一顯示出來時，就立刻呼叫 LevelPlay.LoadRewardedAd(); 來預先載入下一則廣告。這樣當玩家關閉目前這則廣告時，下一則很可能已經準備好了，無須再次等待。

RewardedAd.OnAdDisplayFailed

• 事件解釋：
  當廣告已經載入成功（OnAdLoaded 已觸發），但您嘗試顯示它時卻因為某些原因（例如廣告已過期）而顯示失敗，此事件會被觸發。
• 該做些什麼？
• 1. 錯誤記錄：印出詳細的錯誤訊息，方便分析問題。
  2. 恢復遊戲：如果遊戲已暫停，請確保將其恢復。
  3. 重新載入廣告：再次呼叫 LevelPlay.LoadRewardedAd();，嘗試獲取一則新的廣告。

RewardedAd.OnAdRewarded

• 事件解釋：
  這是最最關鍵的事件。它在玩家完整觀看廣告，並滿足了獲得獎勵的條件時觸發。
• 該做些什麼？
• 1. 給予玩家獎勵！：這是此事件唯一且最重要的職責。無論是增加生命、給予金幣、還是解鎖道具，所有給獎勵的程式碼都應該寫在這裡。
  2. 顯示獎勵動畫/提示：播放一個「獲得金幣+100」的特效或音效，給予玩家正向回饋。
  3. 儲存遊戲進度：如果獎勵是重要物品，記得呼叫存檔功能。

RewardedAd.OnAdClosed

• 事件解釋：
  當使用者關閉廣告（無論是正常看完，還是提早關閉）並返回遊戲時，這個事件會被觸發。
• 該做些什麼？
• 1. 恢復遊戲狀態：如果遊戲被暫停，請在此處恢復（Time.timeScale = 1;），並恢復遊戲音樂。
  2. 檢查是否已給獎勵：OnAdRewarded 事件通常會在 OnAdClosed 之前觸發。但為了保險起見，您可以再次確認。不過，給獎勵的邏輯應該要放在 OnAdRewarded 中，而不是這裡，以防玩家提早關閉廣告卻依然拿到獎勵。

RewardedAd.OnAdClicked

• 事件解釋：
  當玩家在觀看廣告時，點擊了廣告內容（例如點擊了「下載遊戲」按鈕），此事件觸發。
• 該做些什麼？
• • 這主要用於數據分析。您可以記錄玩家點擊廣告的行為，用來分析廣告素材的吸引力。對於遊戲邏輯本身，通常不需要做特別處理。

RewardedAd.OnAdInfoChanged

• 事件解釋：
  這是一個較進階的事件，用於獲取廣告的詳細資訊，例如其 eCPM（千次展示收入）估算值。
• 該做些什麼？
• • 主要用於實現更高級的變現策略，例如分析不同廣告網路的收益表現。對於初學者，可以完全忽略這個事件。

還有什麼問題？

上述是記錄初步串接完流程的筆記，也把對應的官方頁面放上。不過目前我碰到的第一個問題是廣告在第二次載入時，獎勵式廣告的IsAdReady()顯示為False，導致流程判斷無法往下走，正持續排查問題。

如果文章內容有誤，或是想一起討論，歡迎您的回覆，也希望文章能幫助到有緣人。

參考

套件官方文件：點我 (雖然他是8.1版的，但好像還算能參考)

SDK官方文件：點我(這應該是最新維護中的頁面，但還是有些舊內容沒及時更新到)

廣告單元管理說明文件：點我