獎勵廣告

獎勵廣告 可讓您以應用程式內產品來獎勵使用者 影片廣告、可試玩廣告及問卷調查

先備知識

  • Google Mobile Ads SDK 19.7.0 以上版本。
  • 完成入門指南。

一律使用測試廣告進行測試

建構及測試應用程式時，請務必使用測試廣告，而非 現場及正式環境廣告否則可能導致帳戶遭到停權。

要載入測試廣告，最簡單的方法是使用我們專屬的測試廣告單元編號。 Android 獎勵廣告：

ca-app-pub-3940256099942544/5224354917

這項機制經過特別設定，可針對每個請求傳回測試廣告 在您的程式設計、測試和偵錯時，可以免費使用應用程式。只需製作 務必先用廣告單元 ID 取代廣告單元，再發布應用程式。

若要進一步瞭解 Mobile Ads SDK 測試廣告的運作方式，請參閱「測試 Google Ads。

載入獎勵廣告物件

系統會在以下位置呼叫靜態的 load() 方法，載入獎勵廣告 RewardedAd 類別並傳入 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
       }
    })
  }
}

設定 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.")
}

[選用] 驗證伺服器端驗證 (SSV) 回呼

需要在伺服器端使用額外資料的應用程式 驗證回呼應使用 獎勵廣告的自訂資料功能。獎勵廣告中設定的任何字串值 系統會將物件傳遞至 SSV 回呼的 custom_data 查詢參數。如果答案為「否」 如果已設定自訂資料值，custom_data 查詢參數將不會 傳遞到 SSV 回呼中。

以下程式碼範例示範如何設定獎勵廣告的自訂資料 物件，再請求廣告。

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
  }
})

如要設定自訂獎勵字串，就必須在顯示 廣告。

常見問題

初始化呼叫是否有逾時？
10 秒後，Google Mobile Ads SDK 會叫用 OnInitializationCompleteListener (即使中介服務聯播網尚未
如果我收到初始化回呼時，有些中介服務聯播網還沒準備就緒，該怎麼辦？

建議您在 OnInitializationCompleteListener。即使中介服務聯播網尚未準備就緒 Google Mobile Ads SDK 仍會要求該聯播網提供廣告。如果 中介服務聯播網在逾時後完成初始化作業，仍可 服務日後的廣告請求

您可以持續輪詢所有轉接程式的初始化狀態 呼叫 MobileAds.getInitializationStatus() 來修正應用程式工作階段。

如何找出特定中介服務聯播網尚未準備就緒的原因？

AdapterStatus.getDescription() 說明轉接器未準備就緒的原因 服務廣告請求

是否一律會在 onAdDismissedFullScreenContent() 回呼之前呼叫 onUserEarnedReward() 回呼？

Google Ads 的所有 onUserEarnedReward() 呼叫都發生在 onAdDismissedFullScreenContent()。對於透過 中介服務，也就是第三方廣告 回呼順序取決於網路 SDK 的實作方式。廣告聯播網 SDK 提供含獎勵資訊的單一關閉回呼， 中介服務轉接程式會叫用 onUserEarnedReward() onAdDismissedFullScreenContent()。

GitHub 上的範例

後續步驟

探索下列主題：