插頁式獎勵廣告 (Beta 版)

插頁式獎勵廣告是一種獎勵廣告格式，您可在應用程式自然轉換時自動顯示這類廣告，向使用者提供獎勵。與獎勵廣告不同的是，插頁式獎勵廣告不需要等使用者確定選擇觀看即可放送。

必要條件

* Google Mobile Ads SDK 19.2.0 以上版本。

• 完成入門指南。

實作

整合插頁式獎勵廣告的主要步驟如下：

• 載入廣告
• 註冊全螢幕事件回呼
• 處理獎勵回呼
• 顯示廣告
• [選用] 驗證 SSV 回呼

載入廣告

載入廣告時，請使用 RewardedInterstitialAd 類別的靜態 load() 方法。載入方法需要 Context、廣告單元 ID、AdRequest 物件和 RewardedInterstitialAdLoadCallback，以便在廣告載入成功或失敗時收到通知。載入的 RewardedInterstitialAd 物件會在 onRewardedInterstitialAdLoaded() 回呼中提供做為參數。

以下範例說明如何在 MainActivity 中載入 RewardedInterstitialAd。

Java

public class MainActivity extends AppCompatActivity {
  private RewardedInterstitialAd rewardedInterstitialAd;
  private String TAG = "MainActivity";

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    new Thread(
            () -> {
              // Initialize the Google Mobile Ads SDK on a background thread.
              MobileAds.initialize(this, initializationStatus -> {});
              // Load an ad on the main thread.
              runOnUiThread(
                  () -> {
                    loadAd();
                  });
            })
        .start();
  }

  public void loadAd() {
    // Use the test ad unit ID to load an ad.
    RewardedInterstitialAd.load(MainActivity.this, "ca-app-pub-3940256099942544/5354046379",
        new AdRequest.Builder().build(),  new RewardedInterstitialAdLoadCallback() {
      @Override
      public void onAdLoaded(RewardedInterstitialAd ad) {
        Log.d(TAG, "Ad was loaded.");
        rewardedInterstitialAd = ad;
      }
      @Override
      public void onAdFailedToLoad(LoadAdError loadAdError) {
        Log.d(TAG, loadAdError.toString());
        rewardedInterstitialAd = null;
      }
    });
  }
}

Kotlin

import com.google.android.gms.ads.rewardedinterstitial.RewardedInterstitialAd
import com.google.android.gms.ads.rewardedinterstitial.RewardedInterstitialAdLoadCallback

class MainActivity : AppCompactActivity() {

  private var rewardedInterstitialAd? = null
  private final var TAG = "MainActivity"

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    val backgroundScope = CoroutineScope(Dispatchers.IO)
    backgroundScope.launch {
      // Initialize the Google Mobile Ads SDK on a background thread.
      MobileAds.initialize(this@MainActivity) {}
      // Load an ad on the main thread.
      runOnUiThread {
        loadAd()
      }
    }
  }

  private fun loadAd() {
    RewardedInterstitialAd.load(this, "ca-app-pub-3940256099942544/5354046379",
      AdRequest.Builder().build(), object : RewardedInterstitialAdLoadCallback() {
      override fun onAdLoaded(ad: RewardedInterstitialAd) {
        Log.d(TAG, "Ad was loaded.")
        rewardedInterstitialAd = ad
      }

      override fun onAdFailedToLoad(adError: LoadAdError) {
        Log.d(TAG, adError?.toString())
        rewardedInterstitialAd = null
      }
    })
  }
}

提示：您可以在要顯示預先載入的廣告之前，使用廣告載入呼叫建立快取，這樣一來，在需要時就能立即顯示廣告。由於廣告會在一小時後到期，因此您應每小時清除快取，並重新載入新的廣告。

註冊回呼

如要接收呈現事件的通知，您必須將 FullScreenContentCallback 物件傳遞至廣告的 setter。FullScreenContentCallback 物件會處理廣告成功或失敗顯示，以及廣告關閉時的回呼。以下程式碼顯示如何在 RewardedInterstitialAdLoadCallback 中設定匿名 FullScreenContentCallback 物件：

Java

public void loadAd(){
  RewardedInterstitialAd.load(MainActivity.this, "ca-app-pub-3940256099942544/5354046379",
      new AdRequest.Builder().build(), new RewardedInterstitialAdLoadCallback() {
    @Override
    public void onAdLoaded(RewardedInterstitialAd ad) {
      rewardedInterstitialAd = ad;
      rewardedInterstitialAd.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.");
          rewardedInterstitialAd = null;
        }

        @Override
        public void onAdFailedToShowFullScreenContent(AdError adError) {
          // Called when ad fails to show.
          Log.e(TAG, "Ad failed to show fullscreen content.");
          rewardedInterstitialAd = 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.");
        }
      });
    }
    @Override
    public void onAdFailedToLoad(LoadAdError loadAdError) {
      Log.d(TAG, loadAdError.toString());
      rewardedInterstitialAd = null;
    }
  });
}

Kotlin

private fun loadAd() {
  RewardedInterstitialAd.load(this, "ca-app-pub-3940256099942544/5354046379",
    AdRequest.Builder().build(), object : RewardedInterstitialAdLoadCallback() {
    override fun onAdLoaded(ad: RewardedInterstitialAd) {
      rewardedInterstitialAd = ad
      rewardedInterstitialAd?.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.")
          rewardedInterstitialAd = null
        }

        override fun onAdFailedToShowFullScreenContent(adError: AdError) {
          // Called when ad fails to show.
          Log.e(TAG, "Ad failed to show fullscreen content.")
          rewardedInterstitialAd = 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.")
        }
      }
    }

    override fun onAdFailedToLoad(adError: LoadAdError) {
      Log.d(TAG, adError?.toString())
      rewardedInterstitialAd = null
    }
  })
}

處理獎勵

如要顯示插頁式獎勵廣告，請在 MainActivity 中導入 OnUserEarnedRewardListener 介面，以便在使用者獲得獎勵時收到通知。

Java

public class MainActivity extends AppCompatActivity implements OnUserEarnedRewardListener {
  ...
  @Override
  public void onUserEarnedReward(@NonNull RewardItem rewardItem) {
    Log.i(TAG, "User earned reward.");
    // TODO: Reward the user!
  }
}

Kotlin

class MainActivity : AppCompatActivity(), OnUserEarnedRewardListener {
  ...
  override fun onUserEarnedReward(rewardItem: RewardItem) {
    Log.d(TAG, "User earned reward.")
    // TODO: Reward the user!
  }
}

顯示廣告

重點： 向使用者顯示插頁式獎勵廣告前，請務必向使用者顯示簡介畫面，提供明確的獎勵相關訊息，以及在廣告開始前略過廣告的選項。瞭解詳情

實作 OnUserEarnedRewardListener 介面後，您可以使用廣告的 show() 方法呈現廣告，如下所示：

Java

rewardedInterstitialAd.show(/* Activity */ MainActivity.this,/*
    OnUserEarnedRewardListener */ MainActivity.this);

Kotlin

rewardedInterstitialAd?.show(/* Activity */ this, /*
    OnUserEarnedRewardListener */ this)

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

如果應用程式需要在伺服器端驗證回呼中使用額外資料，則應使用獎勵廣告的客製資料功能。獎勵廣告物件上設定的任何字串值，都會傳遞至 SSV 回呼的 custom_data 查詢參數。如果未設定自訂資料值，SSV 回呼中就不會顯示 custom_data 查詢參數值。

以下程式碼範例示範如何在要求廣告前，在獎勵式插頁廣告物件上設定自訂資料。

Java

RewardedInterstitialAd.load(MainActivity.this, "ca-app-pub-3940256099942544/5354046379",
    new AdRequest.Builder().build(),  new RewardedInterstitialAdLoadCallback() {
  @Override
  public void onAdLoaded(RewardedInterstitialAd ad) {
    Log.d(TAG, "Ad was loaded.");
    rewardedInterstitialAd = ad;
    ServerSideVerificationOptions options = new ServerSideVerificationOptions
        .Builder()
        .setCustomData("SAMPLE_CUSTOM_DATA_STRING")
        .build();
    rewardedInterstitialAd.setServerSideVerificationOptions(options);
  }
  @Override
  public void onAdFailedToLoad(LoadAdError loadAdError) {
    Log.d(TAG, loadAdError.toString());
    rewardedInterstitialAd = null;
  }
});

Kotlin

RewardedInterstitialAd.load(this, "ca-app-pub-3940256099942544/5354046379",
    AdRequest.Builder().build(), object : RewardedInterstitialAdLoadCallback() {
  override fun onAdLoaded(ad: RewardedInterstitialAd) {
    Log.d(TAG, "Ad was loaded.")
    rewardedInterstitialAd = ad
    val options = ServerSideVerificationOptions.Builder()
        .setCustomData("SAMPLE_CUSTOM_DATA_STRING")
        .build()
    rewardedInterstitialAd.setServerSideVerificationOptions(options)
  }

  override fun onAdFailedToLoad(adError: LoadAdError) {
    Log.d(TAG, adError?.toString())
    rewardedInterstitialAd = null
  }
})

如要設定自訂獎勵字串，請務必在顯示廣告前設定。

重點： 自訂獎勵字串會以百分比做為轉義，因此在從 SSV 回呼中剖析時，可能需要解碼。

GitHub 上的範例

• 插頁式獎勵廣告範例：Java | Kotlin

後續步驟

請參閱下列主題：

• 使用者隱私權
• 最佳化 SDK 初始化和廣告載入 (Beta 版)