リワード広告を設定する

プラットフォームを選択: Android iOS Unity Flutter Android（以前のバージョン）

リワード広告を使用すると、動画広告、体験プレイ広告、アンケートを操作したユーザーに報酬としてアプリ内アイテムを進呈できます。

このガイドでは、Android アプリにリワード広告を組み込む方法を説明します。

始める前に

先に進む前に、次のことを実施してください。

  • GMA Next-Gen SDK を設定します。
  • テスト用のリワード広告ユニット ID /21775744923/example/rewarded を使用します。
    • アプリの開発とテストでは、配信中の実際の広告ではなく、必ずテスト広告を使用してください。テスト広告ユニット ID を使用しない場合、アカウントが停止される可能性があります。
    • アプリを公開する前に、この ID を広告ユニット ID に置き換えてください。
    • GMA Next-Gen SDK のテスト広告について詳しくは、テスト広告を有効にするをご覧ください。

広告のプリロード（ベータ版）について

GMA Next-Gen SDK の広告のプリロードでは、広告の読み込みとキャッシュが自動化されます。

広告のプリロードには、次のようなメリットがあります。

  • 参照管理: 広告が表示されるまで参照を維持します。
  • 自動再読み込み: キャッシュから広告が取得されると、新しい広告が読み込まれます。
  • 管理された再試行: 広告の読み込みに失敗した場合に、新しい広告を読み込みます。
  • 有効期限の処理: 有効期限が切れる前に広告を更新します。
  • キャッシュの最適化: キャッシュの順序を最適化して、優先度の最も高い広告を配信します。

広告のプリロードを開始する

広告のプリロードを開始するには、GMA Next-Gen SDK の初期化時に start メソッドを 1 回呼び出します。start メソッドを呼び出すと、GMA Next-Gen SDK は自動的に広告をプリロードし、プリロードされた構成の失敗したリクエストを再試行します。

次の例は、広告のプリロードを開始する方法を示しています。

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedAdPreloader.start(adUnitId, preloadConfig)

Java

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedAdPreloader.start(adUnitId, preloadConfig);

AD_UNIT_ID は、実際の広告ユニット ID に置き換えてください。

上記の例では、広告ユニット ID をプリロード ID として使用する方法を示しています。プリロード ID は、広告のプリロード設定を識別するために作成する文字列識別子です。アプリで同じ広告ユニット ID に複数のターゲティング構成が必要な場合は、カスタム文字列識別子を渡します。

広告のプリロードでは、ターゲティング パラメータや広告リクエストの変更はサポートされていません。リクエスト間でターゲティング パラメータを変更する必要がある場合は、単一読み込みを使用します。

プリロードされた広告を取得して表示する

広告を表示する前に、pollAd メソッドを呼び出します。プリロードされた広告オブジェクトを保存しないでください。pollAd メソッドを呼び出すと、GMA Next-Gen SDK は利用可能な広告を取得し、次の広告をバックグラウンドで自動的にプリロードします。表示できる広告がない場合、GMA Next-Gen SDK は広告を返しません。

広告オブジェクトが利用可能になったら、show メソッドを呼び出して広告を表示します。 リワード イベントを処理するには、リワード リスナーを使用します。次の例は、プリロードされた広告を取得して表示する方法を示しています。

Kotlin

private fun pollAndShowAd(activity: Activity, adUnitId: String) {
  // Polling returns the next available ad and loads another ad in the background.
  val ad = RewardedAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "Rewarded ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "Rewarded ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : RewardedAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Rewarded ad recorded an impression.")
      }
    }
  ad.show(activity) { rewardItem -> Log.d(TAG, "User earned reward: ${rewardItem.amount}") }
}

Java

private void pollAndShowAd(Activity activity, String adUnitId) {
  // Polling returns the next available ad and loads another ad in the background.
  final RewardedAd ad = RewardedAdPreloader.pollAd(adUnitId);

  // Interact with the ad object as needed.
  if (ad == null) {
    Log.e(TAG, "Rewarded ad is not available.");
    return;
  }

  Log.d(TAG, "Rewarded ad response info: " + ad.getResponseInfo());
  ad.setAdEventCallback(
      new RewardedAdEventCallback() {
        @Override
        public void onAdImpression() {
          Log.d(TAG, "Rewarded ad recorded an impression.");
        }
      });

  // Show the ad.
  ad.show(
      activity,
      rewardItem -> {
        Log.d(TAG, "User earned reward: " + rewardItem.getAmount());
      });
}

アプリが広告のプレースメントに到達し、show メソッドを呼び出せるようになったら、pollAd メソッドを呼び出します。プリロード コールバックで、または isAdAvailable メソッドをチェックして広告を保持した後に、pollAd メソッドを呼び出さないでください。広告を表示する前に広告メタデータを検査する必要がある場合は、キャッシュから広告を削除せずにレスポンス情報を読み取ります。

広告イベントをリッスンする

広告を表示する前に、広告イベントをリッスンします。次の例では、広告イベントのコールバックを登録しています。

Kotlin

private fun listenToAdEvents() {
  // Listen for ad events.
  val ad = rewardedAd
  if (ad == null) {
    Log.e(TAG, "Rewarded ad is not ready yet.")
    return
  }

  ad.adEventCallback =
    object : RewardedAdEventCallback {
      override fun onAdShowedFullScreenContent() {
        // Rewarded ad did show.
      }

      override fun onAdDismissedFullScreenContent() {
        // Rewarded ad did dismiss.
        rewardedAd = null
      }

      override fun onAdFailedToShowFullScreenContent(
        fullScreenContentError: FullScreenContentError
      ) {
        // Rewarded ad failed to show.
        Log.e(TAG, "Rewarded ad failed to show: ${fullScreenContentError.message}")
      }

      override fun onAdImpression() {
        // Rewarded ad did record an impression.
      }

      override fun onAdClicked() {
        // Rewarded ad did record a click.
      }
    }
}

Java

private void listenToAdEvents() {
  // Listen for ad events.
  if (rewardedAd == null) {
    Log.e(TAG, "Rewarded ad is not ready yet.");
    return;
  }

  rewardedAd.setAdEventCallback(
      new RewardedAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // Rewarded ad did show.
        }

        @Override
        public void onAdDismissedFullScreenContent() {
          // Rewarded ad did dismiss.
          rewardedAd = null;
        }

        @Override
        public void onAdFailedToShowFullScreenContent(
            FullScreenContentError fullScreenContentError) {
          // Rewarded ad failed to show.
          Log.e(TAG, "Rewarded ad failed to show: " + fullScreenContentError.getMessage());
        }

        @Override
        public void onAdImpression() {
          // Rewarded ad did record an impression.
        }

        @Override
        public void onAdClicked() {
          // Rewarded ad did record a click.
        }
      });
}

任意: サーバーサイド認証（SSV）コールバックを検証する

サーバーサイド認証（SSV）コールバックでユーザーとアプリのコンテキストを渡すには、広告を表示する前に広告オブジェクトに認証オプションを設定します。SSV コールバックはセッション状態なしで Google からサーバーに届くため、次のオプションの文字列を添付します。Google は、これらの文字列を SSV コールバックの署名付きクエリ パラメータとしてそのまま転送します。

  • user_id クエリ パラメータ: クレジットを付与するユーザー（内部アカウント ID など）を識別します。
  • custom_data クエリ パラメータ: 報酬のプレースメント、ゲームレベル、サーバー生成のノンスなどのアプリデータを渡します。

値を設定しない場合、Google は SSV コールバックからそのクエリ パラメータを省略します。

次の例では、広告を表示する前に、広告オブジェクトにカスタムデータを設定しています。

Kotlin

RewardedAd.load(
  context,
  AD_UNIT_ID,
  AdRequest.Builder().build(),
  object : RewardedAdLoadCallback() {
    override fun onAdLoaded(ad: RewardedAd) {
      rewardedAd = ad
      val options =
        ServerSideVerificationOptions.Builder().setCustomData("SAMPLE_CUSTOM_DATA_STRING").build()
      rewardedAd?.setServerSideVerificationOptions(options)
    }
  },
)

Java

RewardedAd.load(
    context,
    AD_UNIT_ID,
    new AdRequest.Builder().build(),
    new RewardedAdLoadCallback() {
      @Override
      public void onAdLoaded(RewardedAd ad) {
        rewardedAd = ad;
        ServerSideVerificationOptions options =
            new ServerSideVerificationOptions.Builder()
                .setCustomData("SAMPLE_CUSTOM_DATA_STRING")
                .build();
        rewardedAd.setServerSideVerificationOptions(options);
      }
    });

SAMPLE_CUSTOM_DATA_STRING は、実際のカスタムデータに置き換えてください。

キーポイント: custom_data クエリ パラメータはパーセント エンコードされています。値を解析する前に、サーバーで文字列を URL デコードし、コールバック署名を検証してから、user_id または custom_data クエリ パラメータを信頼します。

省略可: Preload イベントをリッスンする

広告のプリロードを開始するときに、Preload イベントに登録して、広告のプリロードが成功したとき、プリロードに失敗したとき、広告キャッシュが枯渇したときに通知を受け取ります。

次の例は、広告のプリロード イベントを登録する方法を示しています。

Kotlin

val preloadCallback =
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(TAG, "Rewarded preload ad $preloadId failed to load with error: ${adError.message}")
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "Rewarded preload ad $preloadId is not available")
    }

    override fun onAdPreloaded(preloadId: String, responseInfo: ResponseInfo) {
      Log.i(TAG, "Rewarded preload ad $preloadId is available")
    }
  }
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedAdPreloader.start(adUnitId, preloadConfig, preloadCallback)

Java

PreloadCallback preloadCallback =
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(String preloadId, LoadAdError adError) {
        Log.d(
            TAG,
            String.format(
                "Rewarded preload ad %s failed to load with error: %s",
                preloadId, adError.getMessage()));
      }

      @Override
      public void onAdsExhausted(String preloadId) {
        Log.i(TAG, "Rewarded preload ad " + preloadId + " is not available");
      }

      @Override
      public void onAdPreloaded(String preloadId, ResponseInfo responseInfo) {
        Log.i(TAG, "Rewarded preload ad " + preloadId + " is available");
      }
    };

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedAdPreloader.start(adUnitId, preloadConfig, preloadCallback);

広告の読み込みに失敗すると、GMA Next-Gen SDK は自動的に広告をプリロードし、プリロードされた構成の失敗したリクエストを再試行します。失敗コールバックで手動読み込みリクエストを呼び出さないでください。Preload イベントのコールバック メソッドでは、pollAd、destroy、start メソッドを呼び出さないでください。コールバックでこれらのメソッドを呼び出すと、再帰的な読み込みループが呼び出される可能性があります。

省略可: 広告の有無を確認する

広告が利用可能かどうかを確認する必要がある場合は、広告の可用性を確認します。次の例では、プリロードされた広告が利用可能かどうかを確認しています。

Kotlin

private fun isAdAvailable(adUnitId: String): Boolean {
  return RewardedAdPreloader.isAdAvailable(adUnitId)
}

Java

private boolean isAdAvailable(String adUnitId) {
  return RewardedAdPreloader.isAdAvailable(adUnitId);
}

省略可: バッファサイズを設定する

バッファサイズは、メモリに保持されるプリロードされた広告の数を制御します。デフォルトでは、メモリ消費量と広告配信のレイテンシのバランスを取るために、バッファサイズが最適化されます。カスタム バッファサイズを設定して、メモリに保持される広告の数を増減できます。バッファサイズは、プリロードされた広告 2 つ分にすることをおすすめします。トラフィックのほとんどがメモリの少ないデバイスからのものである場合は、バッファサイズを小さくします。

次の例は、バッファサイズを設定する方法を示しています。

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
// Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
RewardedAdPreloader.start(adUnitId, preloadConfig)

Java

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
// Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 2);
RewardedAdPreloader.start(adUnitId, preloadConfig);

プリロード キャッシュの上限

GMA Next-Gen SDK は、すべての広告ユニットとプリロード ID にわたるプリロードされた広告の総数に、アプリ全体の上限を適用します。

  • デフォルトの上限: Google は、最大 6 つのプリロードされた広告をメモリに保持します。この上限は、すべてのフォーマットとプリロード ID で共有されます。
  • プリロード ID ごとに 2 つのバッファサイズを維持することをおすすめします。

省略可: 広告のプリロードを停止する

アプリで広告を配信している間は、プリロードを有効にしておきます。この間は、destroy メソッドを呼び出さないでください。セッションで特定のプリロード ID の広告を再度表示する必要がない場合は、広告のプリロードを停止できます。特定のプリロード ID の広告の読み込みを停止するには、プリロード ID を指定して destroy メソッドを呼び出します。destroy メソッドを呼び出すと、プリロード ID に関連付けられているプリロード済みの広告がすべてキャッシュから削除されます。

次の例は、広告のプリロードを停止する方法を示しています。

Kotlin

private fun stopPreloading(adUnitId: String) {
  // Stops the preloading and destroy preloaded ads.
  RewardedAdPreloader.destroy(adUnitId)
}

Java

private void stopPreloading(String adUnitId) {
  // Stops the preloading and destroy preloaded ads.
  RewardedAdPreloader.destroy(adUnitId);
}

任意: レスポンス情報を読みます。

キャッシュから広告を削除せずに、次にプリロードされた広告のレスポンス情報を読み取ります。広告を表示する前に広告メタデータを検査する必要がある場合は、pollAd メソッドを呼び出す代わりにレスポンス情報を読み取ります。

次の例は、次にプリロードされた広告レスポンス情報を読み取る方法を示しています。

Kotlin

val responseInfo = RewardedAdPreloader.peekAdResponseInfo(preloadId)
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.")
  return
}

Log.d(TAG, "Peeked ad response ID: ${responseInfo.responseId}")

Java

ResponseInfo responseInfo = RewardedAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

Log.d(TAG, "Peeked ad response ID: " + responseInfo.getResponseId());