Custom Events for Banner and Interstitial Ads

このガイドは、Ad Manager メディエーションを使用して次の処理を行う必要があるパブリッシャー様を対象としています。

  • Ad Manager 管理画面で直接サポートされていないネットワークの広告を表示する
  • 広告の代わりにカスタムビューを表示する

カスタム イベントを使用すると、カスタム メディエーション アダプタを記述して、広告スペースに任意のビューを配置できます。このガイドでは、Google が開発したサンプル SDK を使用して、広告をリクエストするカスタム イベントを記述する方法について説明します。カスタム イベントおよびサンプル SDK のソース全体は、GitHub で入手できます。

前提条件

広告フォーマットにカスタム イベントを組み込むには、事前にその広告フォーマットをアプリに組み込んでおく必要があります。関連するガイドは次のとおりです。

以下の例では、はじめに Ad Manager メディエーション内にバナー広告のカスタム イベントを作成します。それには、Ad Manager 管理画面経由でアプリの特定のクラスをポイントするカスタム イベントを定義し、CustomEventBanner を実装してビューを表示する必要があります。この例では、サンプルの広告ネットワークの広告を表示するカスタム イベントを定義します。

カスタム イベントを定義する

カスタム イベントは、Google アド マネージャーの管理画面で定義する必要があります。メディエーションで使用するアド マネージャー収益グループの設定方法については、こちらのヘルプセンター記事をご覧ください。

次のスクリーンショットは、カスタム イベントの設定の例です。

バナー広告をリクエストする

バナー広告をリクエストするには、CustomEventBanner を実装するクラスを定義し、SampleCustomEventBanner という名前を付けます。広告メディエーション フローでカスタム イベントが選択されると、設定で指定したクラス名の requestBannerAd() メソッドが呼び出されます。

上記で定義したオプション パラメータは、requestBannerAd() メソッドの一部としてカスタム イベントに渡されます。通常、このパラメータは、カスタム イベントが読み込む広告を識別するための識別子として機能します。

必要に応じて、ライフサイクル メソッドも実装する必要があります。 ユーザーが PublisherAdView.pause()PublisherAdView.resume() メソッドを呼び出すと、Ad Manager メディエーションによって、それぞれ onPause()onResume() アクティビティ イベントがアダプタに転送されます。サンプル広告ネットワークでは、一時停止や再開の呼び出しがないため、空の実装を提供しています。アダプタが破棄される際、メディエーションによって可能な限り onDestroy() が呼び出されます。必要なクリーンアップはここで行います。

SampleCustomEventBanner の実装例を次に示します。

Java

public class SampleCustomEventBanner implements CustomEventBanner {

    /** The SampleAdView representing a banner ad. */
    private SampleAdView sampleAdView;

    /** The event is being destroyed. Perform any necessary cleanup here. */
    @Override
    public void onDestroy() {
        if (sampleAdView != null) {
            sampleAdView.destroy();
        }
    }

    /**
     * The app is being paused. This call is only forwarded to the adapter if
     * the developer notifies Ad Manager mediation that
     * the app is being paused.
     */
    @Override
    public void onPause() {
        // The sample ad network doesn't have an onPause method, so does nothing.
    }

    /**
     * The app is being resumed. This call is only forwarded to the
     * adapter if the developer notifies Ad Manager
     * mediation that the app is being resumed.
     */
    @Override
    public void onResume() {
        // The sample ad network doesn't have an onResume method, so does nothing.
    }

    @Override
    public void requestBannerAd(Context context,
            CustomEventBannerListener listener,
            String serverParameter,
            AdSize size,
            MediationAdRequest mediationAdRequest,
            Bundle customEventExtras) {

        sampleAdView = new SampleAdView(context);

        // Assumes that the serverParameter is the AdUnit for the Sample Network.
        sampleAdView.setAdUnit(serverParameter);

        sampleAdView.setSize(new SampleAdSize(size.getWidth(), size.getHeight()));

        // Implement a SampleAdListener and forward callbacks to Ad Manager.
        // The callback forwarding is handled by SampleBannerEventFowarder.
        sampleAdView.setAdListener(new SampleCustomBannerEventForwarder(listener, sampleAdView));

        // Make an ad request.
        sampleAdView.fetchAd(createSampleRequest(mediationAdRequest));

        }

    private SampleAdRequest createSampleRequest(MediationAdRequest mediationAdRequest) {
        SampleAdRequest request = new SampleAdRequest();
        request.setTestMode(mediationAdRequest.isTesting());
        request.setKeywords(mediationAdRequest.getKeywords());
        return request;
        }
}

Kotlin

class SampleCustomEventBanner : CustomEventBanner {

    /** The SampleAdView representing a banner ad. */
    private lateinit var mSampleAdView: SampleAdView

    /** The event is being destroyed. Perform any necessary cleanup here. */
    override fun onDestroy() {
        mSampleAdView.destroy()
    }

    /**
     * The app is being paused. This call is only forwarded to the adapter if
     * the developer notifies Ad Manager mediation that
     * the app is being paused.
     */
    override fun onPause() {
        // The sample ad network doesn't have an onPause method, so does nothing.
    }

    /**
     * The app is being resumed. This call is only forwarded to the
     * adapter if the developer notifies Ad Manager
     * mediation that the app is being resumed.
     */
    override fun onResume() {
        // The sample ad network doesn't have an onResume method, so does nothing.
    }

    override fun requestBannerAd(context: Context,
                                 listener: CustomEventBannerListener,
                                 serverParameter: String,
                                 size: AdSize,
                                 mediationAdRequest: MediationAdRequest,
                                 customEventExtras: Bundle?) {

        mSampleAdView = SampleAdView(context)

        // Assumes that the serverParameter is the AdUnit for the Sample Network.
        mSampleAdView.adUnit = serverParameter
        mSampleAdView.size = SampleAdSize(size.width, size.height)

        // Implement a SampleAdListener and forward callbacks to
        // Ad Manager mediation. The callback forwarding
        // is handled by SampleBannerEventFowarder.
        mSampleAdView.adListener = SampleCustomBannerEventForwarder(listener, mSampleAdView)

        // Make an ad request.
        mSampleAdView.fetchAd(createSampleRequest(mediationAdRequest))
    }

    private fun createSampleRequest(mediationAdRequest: MediationAdRequest): SampleAdRequest {
        val request = SampleAdRequest()
        request.testMode = mediationAdRequest.isTesting
        request.keywords = mediationAdRequest.keywords
        return request
    }
}

カスタム イベントのリクエストで広告ネットワークの追加パラメータを送信する(省略可)

カスタム イベントに追加のパラメータを送信する必要がある場合は、PublisherAdRequest.Builder クラスの addCustomEventExtrasBundle() メソッド を使用します。カスタム イベント アダプタのクラスとカスタム イベント アダプタによって予期される追加パラメータのバンドルを渡す必要があります。

上記で定義した SampleCustomEventBanner クラスに SampleExtra パラメータを渡す方法を示したコード スニペットは、次のようになります。

Bundle extras = new Bundle();
extras.putBoolean("SampleExtra", true);

PublisherAdRequest request = new PublisherAdRequest.Builder()
        .addCustomEventExtrasBundle(SampleCustomEventBanner.class, extras)
        .build();

addCustomEventExtras() を呼び出す際に正しいカスタム イベント クラスおよびカスタム イベント リクエストのバンドルを指定しなければ、アダプタが受け取る bundle パラメータは null になります。

Ad Manager メディエーションに通知する

カスタム イベントでは、広告の読み込みの成否を、CustomEventBannerListener インターフェース経由でメディエーションに通知する必要があります。これを行わないと、カスタム イベントはタイムアウトし、広告メディエーションは次のネットワークに進みます。

ネットワーク用の広告リスナーを実装し、CustomEventBannerListener で関連するコールバックを呼び出して、Ad Manager メディエーションにメッセージを返します。

Ad Manager メディエーションでは、次のコールバックがサポートされています。

メソッド 呼び出すタイミング
onAdLoaded() バナー リクエストが成功したとき
onAdFailedToLoad() バナー リクエストが失敗したとき
onAdClicked() バナーがクリックされたとき
onAdOpened() バナーがフルスクリーン ビューで表示されたとき
onAdClosed() ユーザーがバナーをクリックした後で、アプリに戻るとき
onAdLeftApplication() ユーザーがバナー経由でアプリから離れたとき

SampleCustomBannerEventForwarder の実装例を次に示します。

Java

public class SampleCustomBannerEventForwarder extends SampleAdListener {
    private CustomEventBannerListener mBannerListener;
    private SampleAdView mAdView;

    /**
     * Creates a new {@code SampleBannerEventForwarder}.
     * @param listener A {@link CustomEventBannerListener} that should receive
     *                 forwarded events.
     * @param adView   A {@link SampleAdView}.
     */
    public SampleCustomBannerEventForwarder(
            CustomEventBannerListener listener, SampleAdView adView) {
        this.mBannerListener = listener;
        this.mAdView = adView;
    }

    @Override
    public void onAdFetchSucceeded() {
        mBannerListener.onAdLoaded(mAdView);
    }

    @Override
    public void onAdFetchFailed(SampleErrorCode errorCode) {
        switch (errorCode) {
            case UNKNOWN:
                mBannerListener.onAdFailedToLoad(PublisherAdRequest.ERROR_CODE_INTERNAL_ERROR);
                break;
            case BAD_REQUEST:
                mBannerListener.onAdFailedToLoad(PublisherAdRequest.ERROR_CODE_INVALID_REQUEST);
                break;
            case NETWORK_ERROR:
                mBannerListener.onAdFailedToLoad(PublisherAdRequest.ERROR_CODE_NETWORK_ERROR);
                break;
            case NO_INVENTORY:
                mBannerListener.onAdFailedToLoad(PublisherAdRequest.ERROR_CODE_NO_FILL);
                break;
        }
    }

    @Override
    public void onAdFullScreen() {
        mBannerListener.onAdClicked();
        mBannerListener.onAdOpened();
        // Only call onAdLeftApplication if your ad network actually exits the developer's app.
        mBannerListener.onAdLeftApplication();
    }

    @Override
    public void onAdClosed() {
        mBannerListener.onAdClosed();
    }
}

Kotlin

class SampleCustomBannerEventForwarder(private val mBannerListener: CustomEventBannerListener,
                                       private val mAdView: SampleAdView) : SampleAdListener() {

    override fun onAdFetchSucceeded() {
        mBannerListener.onAdLoaded(mAdView)
    }

    override fun onAdFetchFailed(errorCode: SampleErrorCode) {
        when (errorCode) {
            UNKNOWN -> mBannerListener.onAdFailedToLoad(PublisherAdRequest.ERROR_CODE_INTERNAL_ERROR)
            BAD_REQUEST -> mBannerListener.onAdFailedToLoad(PublisherAdRequest.ERROR_CODE_INVALID_REQUEST)
            NETWORK_ERROR -> mBannerListener.onAdFailedToLoad(PublisherAdRequest.ERROR_CODE_NETWORK_ERROR)
            NO_INVENTORY -> mBannerListener.onAdFailedToLoad(PublisherAdRequest.ERROR_CODE_NO_FILL)
        }
    }

    override fun onAdFullScreen() {
        mBannerListener.onAdClicked()
        mBannerListener.onAdOpened()
        // Only call onAdLeftApplication if your ad network actually exits the developer's app.
        mBannerListener.onAdLeftApplication()
    }

    override fun onAdClosed() {
        mBannerListener.onAdClosed()
    }
}

インタースティシャル広告のカスタム イベント

インタースティシャル広告のカスタム イベントを実装するには、バナー広告のカスタム イベントと同じように、まず Ad Manager メディエーション内にインタースティシャル広告のカスタム イベントを作成します。次に、CustomEventInterstitial を実装してメディエーションに通知します。この例では、これまでと同様にサンプル広告ネットワークを使用します。

カスタム イベントを定義する

アド マネージャーの管理画面から、インタースティシャル広告のカスタム イベントを定義できます。

[Class Name] には必ずフルパスを入力します。 [Parameter] には、カスタム イベントに実装するネットワークに対して、広告リクエストを行うために必要な情報を入力します。

インタースティシャル広告をリクエストする

インタースティシャル広告をリクエストするには、CustomEventInterstitial を実装するクラスを定義し、SampleCustomEventInterstitial という名前を付けます。メディエーション フローでカスタム イベントが選択されると、設定で指定したクラス名の requestInterstitialAd() メソッドがメディエーションによって呼び出されます。このメソッドで提供されるパラメータを使用して、目的のネットワークに対してインタースティシャル広告のリクエストを実行します。次の例は、カスタム イベント経由でサンプル広告ネットワークのインタースティシャル広告をリクエストする方法を示しています。

SampleCustomEventInterstitial の実装例を次に示します。

Java

public class SampleCustomEventInterstitial implements CustomEventInterstitial {

    /** Represents a SampleInterstitial. */
    private SampleInterstitial sampleInterstitial;

    @Override
    public void requestInterstitialAd(Context context,
            CustomEventInterstitialListener listener,
            String serverParameter,
            MediationAdRequest mediationAdRequest,
            Bundle customEventExtras) {
        /**
         * In this method, you should:
         * 1. Create your interstitial ad.
         * 2. Set your ad network's listener.
         * 3. Make an ad request.
         */

        sampleInterstitial = new SampleInterstitial(context);

        // Here we're assuming the serverParameter is the ad unit for the sample ad network.
        sampleInterstitial.setAdUnit(serverParameter);

        // Implement a SampleAdListener and forward callbacks to
        // Ad Manager.
        sampleInterstitial.setAdListener(new SampleCustomInterstitialEventForwarder(listener));

        // Make an ad request.
        sampleInterstitial.fetchAd(createSampleRequest(mediationAdRequest));
    }

    /**
     * Helper method to create a SampleAdRequest.
     * @param mediationAdRequest The mediation request with targeting information.
     * @return The created SampleAdRequest.
     */
    private SampleAdRequest createSampleRequest(MediationAdRequest mediationAdRequest) {
        SampleAdRequest request = new SampleAdRequest();
        request.setTestMode(mediationAdRequest.isTesting());
        request.setKeywords(mediationAdRequest.getKeywords());
        return request;
    }

    @Override
    public void showInterstitial() {
        // Show your interstitial ad.
        sampleInterstitial.show();
    }

    /** The event is being destroyed. Perform any necessary cleanup here. */
    @Override
    public void onDestroy() {
        if (sampleInterstitial != null) {
            sampleInterstitial.destroy();
        }
    }

    /**
     * The app is being paused. This call is only forwarded to the adapter if
     * the developer notifies Ad Manager mediation
     * that the app is being paused.
     */
    @Override
    public void onPause() {
        // The sample ad network doesn't have an onPause method, so does nothing.
    }

    /**
     * The app is being resumed. This call is only forwarded to the
     * adapter if the developer notifies Ad Manager
     * mediation that the app is being resumed.
     */
    @Override
    public void onResume() {
        // The sample ad network doesn't have an onResume method, so does nothing.
    }
}

Kotlin

class SampleCustomEventInterstitial : CustomEventInterstitial {

    /** Represents a SampleInterstitial.  */
    private lateinit var mSampleInterstitial: SampleInterstitial

    override fun requestInterstitialAd(context: Context,
                                       listener: CustomEventInterstitialListener,
                                       serverParameter: String,
                                       mediationAdRequest: MediationAdRequest,
                                       customEventExtras: Bundle?) {
        /**
         * In this method, you should:
         * 1. Create your interstitial ad.
         * 2. Set your ad network's listener.
         * 3. Make an ad request.
         */

        mSampleInterstitial = SampleInterstitial(context)

        // Here we're assuming the serverParameter is the ad unit for the sample ad network.
        mSampleInterstitial.adUnit = serverParameter

        // Implement a SampleAdListener and forward callbacks to
        // Ad Manager mediation.
        mSampleInterstitial.adListener = SampleCustomInterstitialEventForwarder(listener)

        // Make an ad request.
        mSampleInterstitial.fetchAd(createSampleRequest(mediationAdRequest))
    }

    /**
     * Helper method to create a [SampleAdRequest].
     * @param mediationAdRequest The mediation request with targeting information.
     * *
     * @return The created [SampleAdRequest].
     */
    private fun createSampleRequest(mediationAdRequest: MediationAdRequest): SampleAdRequest {
        val request = SampleAdRequest()
        request.testMode = mediationAdRequest.isTesting
        request.keywords = mediationAdRequest.keywords
        return request
    }

    override fun showInterstitial() {
        // Show your interstitial ad.
        mSampleInterstitial.show()
    }

    /** The event is being destroyed. Perform any necessary cleanup here. */
    override fun onDestroy() {
        mSampleInterstitial.destroy()
    }

    /**
     * The app is being paused. This call is only forwarded to the adapter if
     * the developer notifies Ad Manager mediation that
     * the app is being paused.
     */
    override fun onPause() {
        // The sample ad network doesn't have an onPause method, so does nothing.
    }

    /**
     * The app is being resumed. This call is only forwarded to the adapter if
     * the developer notifies Ad Manager mediation that
     * the app is being resumed.
     */
    override fun onResume() {
        // The sample ad network doesn't have an onResume method, so does nothing.
    }
}

インタースティシャルのカスタム イベント インターフェースでは、showInterstitial() メソッドを実装する必要があります。Google Mobile Ads SDK にインタースティシャル広告の表示をリクエストすると、メディエーションによってこのメソッドが呼び出されます。

カスタム イベントのリクエストで広告ネットワークの追加パラメータを送信する(省略可)

カスタム イベントに追加のパラメータを送信する必要がある場合は、PublisherAdRequest.Builder クラスの addCustomEventExtrasBundle() メソッド を使用します。カスタム イベント アダプタのクラスとカスタム イベント アダプタによって予期される追加パラメータのバンドルを渡す必要があります。

上記で定義した SampleCustomEventInterstitial クラスに "SampleExtra" パラメータを渡す方法を示したコード スニペットは、次のようになります。

Bundle extras = new Bundle();
extras.putBoolean("SampleExtra", true);

PublisherAdRequest request = new PublisherAdRequest.Builder()
        .addCustomEventExtrasBundle(SampleCustomEventInterstitial.class, extras)
        .build();

addCustomEventExtrasBundle() を呼び出す際に正しいカスタム イベント クラスおよびカスタム イベント リクエストのバンドルを指定しなければ、アダプタが受け取る bundle パラメータは null になります。

Ad Manager メディエーションに通知する

バナー広告のカスタム イベントのサンプルと同じように、ネットワークの広告リスナーを実装して、メッセージを Ad Manager メディエーションに返します。

以下に示す SampleCustomInterstitialEventForwarder クラスでは、SampleAdListener インターフェースを実装し、サンプル広告ネットワークからコールバックを転送しています。

Java

public class SampleCustomInterstitialEventForwarder extends SampleAdListener {
    private CustomEventInterstitialListener mInterstitialListener;

    /**
     * Creates a new SampleInterstitialEventForwarder.
     * @param listener An AdMob CustomEventInterstitialListener that should
     *                 receive forwarded events.
     */
    public SampleCustomInterstitialEventForwarder(CustomEventInterstitialListener listener) {
        this.mInterstitialListener = listener;
    }

    @Override
    public void onAdFetchSucceeded() {
        mInterstitialListener.onAdLoaded();
    }

    @Override
    public void onAdFetchFailed(SampleErrorCode errorCode) {
        switch (errorCode) {
            case UNKNOWN:
                mInterstitialListener.onAdFailedToLoad(PublisherAdRequest.ERROR_CODE_INTERNAL_ERROR);
                break;
            case BAD_REQUEST:
                mInterstitialListener.onAdFailedToLoad(PublisherAdRequest.ERROR_CODE_INVALID_REQUEST);
                break;
            case NETWORK_ERROR:
                mInterstitialListener.onAdFailedToLoad(PublisherAdRequest.ERROR_CODE_NETWORK_ERROR);
                break;
            case NO_INVENTORY:
                mInterstitialListener.onAdFailedToLoad(PublisherAdRequest.ERROR_CODE_NO_FILL);
                break;
        }
    }

    @Override
    public void onAdFullScreen() {
        mInterstitialListener.onAdOpened();
        // Only call onAdLeftApplication if your ad network actually exits the developer's app.
        mInterstitialListener.onAdLeftApplication();
    }

    @Override
    public void onAdClosed() {
        mInterstitialListener.onAdClosed();
    }
}

Kotlin

class SampleCustomInterstitialEventForwarder(private val mInterstitialListener: CustomEventInterstitialListener)
        : SampleAdListener() {

    override fun onAdFetchSucceeded() {
        mInterstitialListener.onAdLoaded()
    }

    override fun onAdFetchFailed(errorCode: SampleErrorCode) {
        when (errorCode) {
            UNKNOWN -> mInterstitialListener.onAdFailedToLoad(PublisherAdRequest.ERROR_CODE_INTERNAL_ERROR)
            BAD_REQUEST -> mInterstitialListener.onAdFailedToLoad(PublisherAdRequest.ERROR_CODE_INVALID_REQUEST)
            NETWORK_ERROR -> mInterstitialListener.onAdFailedToLoad(PublisherAdRequest.ERROR_CODE_NETWORK_ERROR)
            NO_INVENTORY -> mInterstitialListener.onAdFailedToLoad(PublisherAdRequest.ERROR_CODE_NO_FILL)
        }
    }

    override fun onAdFullScreen() {
        mInterstitialListener.onAdOpened()
        // Only call onAdLeftApplication if your ad network actually exits the developer's app.
        mInterstitialListener.onAdLeftApplication()
    }

    override fun onAdClosed() {
        mInterstitialListener.onAdClosed()
    }
}

これで、インタースティシャル広告のカスタム イベントの実装が完了しました。サンプル全体は GitHub で入手できます。このサンプルは、すでにサポートされている広告ネットワークで使用することができます。また、変更を加えてカスタム インタースティシャル広告を表示することもできます。

フィードバックを送信...

Mobile Ads SDK for Android
Mobile Ads SDK for Android
ご不明な点がありましたら、Google のサポートページをご覧ください。