必要條件
- Google Mobile Ads SDK 19.7.0 以上版本。
- 完成入門指南。
一律使用測試廣告進行測試
打造及測試應用程式時,請務必使用測試廣告,而非實際的廣告。否則帳戶可能會遭到停權。
如要載入測試廣告,最簡單的方法是使用 Android 獎勵廣告專用的測試廣告單元 ID:
ca-app-pub-3940256099942544/5224354917
這個功能經過特別設計,可針對每項要求傳回測試廣告,您可以在編寫、測試及偵錯時,自由在應用程式中使用。您只要在發布應用程式前將其 ID 換成您自己的廣告單元 ID 即可。
如要進一步瞭解 Mobile Ads SDK 的測試廣告的運作方式,請參閱測試廣告。
載入獎勵廣告物件
呼叫 RewardedAd
類別上的靜態 load()
方法並傳入 RewardedAdLoadCallback
後,即可載入獎勵廣告。這通常位於 Activity
的 onCreate()
方法中。請注意,如同其他格式載入回呼,RewardedAdLoadCallback
會使用 LoadAdError
提供較高的擬真度錯誤詳細資料。
Java
import com.google.android.gms.ads.rewarded.RewardedAd; public class MainActivity extends Activity { private RewardedAd rewardedAd; private final String TAG = "MainActivity"; @Override protected void onCreate(Bundle savedInstanceState) { AdRequest adRequest = new AdRequest.Builder().build(); RewardedAd.load(this, "ca-app-pub-3940256099942544/5224354917", adRequest, new RewardedAdLoadCallback() { @Override public void onAdFailedToLoad(@NonNull LoadAdError loadAdError) { // Handle the error. Log.d(TAG, loadAdError.toString()); rewardedAd = null; } @Override public void onAdLoaded(@NonNull RewardedAd ad) { rewardedAd = ad; Log.d(TAG, "Ad was loaded."); } }); } }
Kotlin
class MainActivity : AppCompatActivity() { private var rewardedAd: RewardedAd? = null private final var TAG = "MainActivity" override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_main) var adRequest = AdRequest.Builder().build() RewardedAd.load(this,"ca-app-pub-3940256099942544/5224354917", adRequest, object : RewardedAdLoadCallback() { override fun onAdFailedToLoad(adError: LoadAdError) { Log.d(TAG, adError?.toString()) rewardedAd = null } override fun onAdLoaded(ad: RewardedAd) { Log.d(TAG, "Ad was loaded.") rewardedAd = ad } }) } }
[選用] 驗證伺服器端驗證 (SSV) 回呼
如果應用程式需要在伺服器端驗證回呼中提供額外資料,則應使用獎勵廣告的自訂資料功能。系統會將獎勵物件設定的任何字串值傳遞至 SSV 回呼的 custom_data
查詢參數。如未設定自訂資料值,SSV 回呼就不會顯示 custom_data
查詢參數值。
下列程式碼範例示範如何在請求廣告前,為獎勵廣告物件設定自訂資料。
Java
RewardedAd.load(MainActivity.this, "ca-app-pub-3940256099942544/5354046379", new AdRequest.Builder().build(), new RewardedAdLoadCallback() { @Override public void onAdLoaded(RewardedAd ad) { Log.d(TAG, "Ad was loaded."); rewardedAd = ad; ServerSideVerificationOptions options = new ServerSideVerificationOptions .Builder() .setCustomData("SAMPLE_CUSTOM_DATA_STRING") .build(); rewardedAd.setServerSideVerificationOptions(options); } @Override public void onAdFailedToLoad(LoadAdError loadAdError) { Log.d(TAG, loadAdError.toString()); rewardedAd = null; } });
Kotlin
RewardedAd.load(this, "ca-app-pub-3940256099942544/5354046379", AdRequest.Builder().build(), object : RewardedAdLoadCallback() { override fun onAdLoaded(ad: RewardedAd) { Log.d(TAG, "Ad was loaded.") rewardedInterstitialAd = ad val options = ServerSideVerificationOptions.Builder() .setCustomData("SAMPLE_CUSTOM_DATA_STRING") .build() rewardedAd.setServerSideVerificationOptions(options) } override fun onAdFailedToLoad(adError: LoadAdError) { Log.d(TAG, adError?.toString()) rewardedAd = null } })
如果您要設定自訂獎勵字串,則必須先完成設定才能顯示廣告。
設定 FullScreenContentCallback
FullScreenContentCallback
會處理顯示 RewardedAd
的相關事件。在顯示 RewardedAd
之前,請務必設定回呼,如下所示:
Java
rewardedAd.setFullScreenContentCallback(new FullScreenContentCallback() { @Override public void onAdClicked() { // Called when a click is recorded for an ad. Log.d(TAG, "Ad was clicked."); } @Override public void onAdDismissedFullScreenContent() { // Called when ad is dismissed. // Set the ad reference to null so you don't show the ad a second time. Log.d(TAG, "Ad dismissed fullscreen content."); rewardedAd = null; } @Override public void onAdFailedToShowFullScreenContent(AdError adError) { // Called when ad fails to show. Log.e(TAG, "Ad failed to show fullscreen content."); rewardedAd = null; } @Override public void onAdImpression() { // Called when an impression is recorded for an ad. Log.d(TAG, "Ad recorded an impression."); } @Override public void onAdShowedFullScreenContent() { // Called when ad is shown. Log.d(TAG, "Ad showed fullscreen content."); } });
Kotlin
rewardedAd?.fullScreenContentCallback = object: FullScreenContentCallback() { override fun onAdClicked() { // Called when a click is recorded for an ad. Log.d(TAG, "Ad was clicked.") } override fun onAdDismissedFullScreenContent() { // Called when ad is dismissed. // Set the ad reference to null so you don't show the ad a second time. Log.d(TAG, "Ad dismissed fullscreen content.") rewardedAd = null } override fun onAdFailedToShowFullScreenContent(adError: AdError?) { // Called when ad fails to show. Log.e(TAG, "Ad failed to show fullscreen content.") rewardedAd = null } override fun onAdImpression() { // Called when an impression is recorded for an ad. Log.d(TAG, "Ad recorded an impression.") } override fun onAdShowedFullScreenContent() { // Called when ad is shown. Log.d(TAG, "Ad showed fullscreen content.") } }
顯示廣告
顯示獎勵廣告時,您將使用 OnUserEarnedRewardListener
物件來處理獎勵事件。
Java
if (rewardedAd != null) { Activity activityContext = MainActivity.this; rewardedAd.show(activityContext, new OnUserEarnedRewardListener() { @Override public void onUserEarnedReward(@NonNull RewardItem rewardItem) { // Handle the reward. Log.d(TAG, "The user earned the reward."); int rewardAmount = rewardItem.getAmount(); String rewardType = rewardItem.getType(); } }); } else { Log.d(TAG, "The rewarded ad wasn't ready yet."); }
Kotlin
rewardedAd?.let { ad -> ad.show(this, OnUserEarnedRewardListener { rewardItem -> // Handle the reward. val rewardAmount = rewardItem.amount val rewardType = rewardItem.type Log.d(TAG, "User earned the reward.") }) } ?: run { Log.d(TAG, "The rewarded ad wasn't ready yet.") }
常見問題
- 初始化呼叫有逾時嗎?
- 10 秒後,即使中介服務聯播網尚未完成初始化作業,Google Mobile Ads SDK 也會叫用
OnInitializationCompleteListener
。 - 如果我收到初始化初始化作業,但部分中介服務聯播網尚未完成,該怎麼辦?
建議您在
OnInitializationCompleteListener
回呼內載入廣告。即使中介服務聯播網尚未準備就緒,Google Mobile Ads SDK 仍會要求該聯播網放送廣告。因此,如果中介服務聯播網在逾時後完成初始化,仍可在該工作階段中處理日後的廣告請求。您可以藉由呼叫
MobileAds.getInitializationStatus()
,繼續在整個應用程式工作階段中輪詢所有轉接程式的初始化狀態。- 如何找出特定中介服務聯播網尚未準備就緒的原因?
AdapterStatus.getDescription()
說明轉接器為何不能用來處理廣告請求,onUserEarnedReward()
回呼一律會在onAdDismissedFullScreenContent()
回呼之前呼叫嗎?如果是 Google 廣告,所有
onUserEarnedReward()
呼叫都會發生在onAdDismissedFullScreenContent()
之前。透過中介服務放送的廣告,第三方廣告聯播網的導入作業會決定回呼順序。如果廣告聯播網 SDK 提供單一關閉回呼與獎勵資訊,中介服務轉接程式會在onAdDismissedFullScreenContent()
之前叫用onUserEarnedReward()
。
GitHub 上的範例
後續步驟
進一步瞭解使用者隱私。