ネイティブ カスタム イベント

このガイドは、AdMob でサポートされている広告ネットワーク以外のネットワークのネイティブ広告を、AdMob メディエーションを使って読み込み、表示したいと考えているパブリッシャー様を対象としています(AdMob メディエーションを使用してバナー広告またはインタースティシャル広告を読み込んで表示する方法については、カスタム イベントを参照してください)。カスタム イベントは、別のネットワークから広告をリクエストする機能を持つメディエーション アダプタ クラスです。これらのクラスのいずれかの名前を広告ユニットのメディエーション設定に追加すると、SDK はそれをインスタンス化して使用し、広告を取得します。ネイティブのカスタム イベント クラスは、次の機能を持つ必要があります。

  • メディエーション対象ネットワークに対してネイティブ広告をリクエストする。
  • メディエーション対象ネットワークの SDK から Google Mobile Ads SDK にイベントを転送する。
  • UnifiedNativeAdMapper を使って、メディエーション対象のネイティブ広告を AdMob のネイティブ広告インターフェースにマッピングする。

それぞれのタスクについては、以下で説明します。また、GitHub リポジトリで、サンプル カスタム イベント プロジェクトのソース全体を入手することもできます。

前提条件

AdMob のカスタム イベントを実装するには、まずプロジェクトに Mobile Ads SDK を統合しておく必要があります。さらに、 AdRequestの実行メディエーションの仕組みに関する資料もご確認ください。

サンプル SDK

このガイドで使用されているコードは、「サンプル SDK」を含むサンプル カスタム イベント プロジェクトから取得したものです。この模擬 SDK は、他の広告ネットワークの SDK をメディエーションするカスタム イベントをビルドする方法を示すサンプルの中で使用されます。

サンプル SDK には広告ネットワークの本稼働 SDK に見られるものと同様のクラスがあり、SampleNativeAdRequest などのリクエスト オブジェクトや SampleNativeAdLoader などの広告ローダーのほか、クラス、定数、さらに実際のネットワークの SDK をシミュレートする管理画面があります。ただし、作成される広告はサンプルですので、追加のネットワーク トラフィックは発生しません。

ネイティブ広告のリクエスト

requestNativeAd() メソッド

カスタム イベント クラスは CustomEventNative インターフェースを実装する必要があります。このインターフェースには、カスタム イベントからネイティブ広告をリクエストするために Google Mobile Ads SDK で使われるメソッドが含まれます。

Java

    void requestNativeAd(Context context,
            CustomEventNativeListener listener,
            String serverParameter,
            NativeMediationAdRequest mediationAdRequest,
            Bundle customEventExtras);
    

Kotlin

    override fun requestNativeAd(context: Context,
            listener: CustomEventNativeListener,
            serverParameter: String,
            mediationAdRequest: NativeMediationAdRequest,
            customEventExtras: Bundle?)
    

このメソッドが呼び出されると、カスタム イベントは、メディエーション対象ネットワークからネイティブ広告を非同期的にリクエストします。次に示す requestNativeAd() のパラメータは、リクエストの作成時にカスタム イベントで使用できる情報を伝達します。

  • serverParameter - 広告ユニットのメディエーション設定にカスタム イベントを追加する際、パブリッシャーは、各リクエストとともに渡される文字列値を入力できます。このパラメータはその値(通常は、メディエーション対象ネットワークによって発行された他の広告ユニット ID)を保持します。
  • mediationAdRequest - NativeMediationAdRequest オブジェクトのひとつで、単一リクエストの固有プロパティ(リクエストされたネイティブ フォーマットなど)が含まれます。NativeMediationAdRequestMediationAdRequest のサブクラスであるため、リクエスト時にパブリッシャーによって提供される他のターゲティング情報のプロパティも含まれます。
  • customEventExtras - パブリッシャーから提供されたリクエストに関連する追加情報を含む Bundle。広告リクエストを作成する際、パブリッシャーは addNetworkExtrasBundle() メソッドを使用して、特定のメディエーション アダプタおよびカスタム イベントの情報を含めることができます。パブリッシャーによって追加された指定カスタム イベント クラスの追加パラメータは、このパラメータの中に含まれます。

リクエスト情報を伝達するパラメータに加えて、次の 2 つのパラメータがあります。

  • context - カスタム イベントで必要な場合に使用できる Context オブジェクト。
  • listener - イベントを転送するためにカスタム イベントで使用される CustomEventNativeListener オブジェクト。

listener オブジェクトは、イベントを Google Mobile Ads SDK に送信するときに使用されるため、特に重要です。送信方法は、Mobile Ads SDK にイベントを転送するで説明します。

サンプルのカスタム イベント プロジェクトから抜粋した、requestNativeAd() メソッドの実装部分のコード スニペットを次に示します。

SampleCustomEvent(抜粋)

Java

    @Override
    public void requestNativeAd(Context context,
                                CustomEventNativeListener customEventNativeListener,
                                String serverParameter,
                                NativeMediationAdRequest nativeMediationAdRequest,
                                Bundle extras) {
        // Create one of the Sample SDK's ad loaders from which to request ads.
        SampleNativeAdLoader loader = new SampleNativeAdLoader(context);
        loader.setAdUnit(serverParameter);

        // Create a native request to give to the SampleNativeAdLoader.
        SampleNativeAdRequest request = new SampleNativeAdRequest();
        NativeAdOptions options = nativeMediationAdRequest.getNativeAdOptions();
        if (options != null) {
            // If the NativeAdOptions' shouldReturnUrlsForImageAssets is true, the adapter should
            // send just the URLs for the images.
            request.setShouldDownloadImages(!options.shouldReturnUrlsForImageAssets());

            // If your network does not support any of the following options, please make sure
            // that it is documented in your adapter's documentation.
            request.setShouldDownloadMultipleImages(options.shouldRequestMultipleImages());
            switch (options.getImageOrientation()) {
                case NativeAdOptions.ORIENTATION_LANDSCAPE:
                    request.setPreferredImageOrientation(
                            SampleNativeAdRequest.IMAGE_ORIENTATION_LANDSCAPE);
                    break;
                case NativeAdOptions.ORIENTATION_PORTRAIT:
                    request.setPreferredImageOrientation(
                            SampleNativeAdRequest.IMAGE_ORIENTATION_PORTRAIT);
                    break;
                case NativeAdOptions.ORIENTATION_ANY:
                default:
                    request.setPreferredImageOrientation(
                            SampleNativeAdRequest.IMAGE_ORIENTATION_ANY);
            }
        }

        if (!nativeMediationAdRequest.isUnifiedNativeAdRequested()) {
            Log.e(TAG, "Failed to load ad. Request must be for unified native ads.");
            customEventNativeListener.onAdFailedToLoad(AdRequest.ERROR_CODE_INVALID_REQUEST);
            return;
        }

        loader.setNativeAdListener(
                new SampleCustomNativeEventForwarder(customEventNativeListener, options));

        // Begin a request.
        loader.fetchAd(request);
    }
    

Kotlin

    override fun requestNativeAd(context: Context,
                                 customEventNativeListener: CustomEventNativeListener,
                                 serverParameter: String,
                                 nativeMediationAdRequest: NativeMediationAdRequest,
                                 extras: Bundle) {
        // Create one of the Sample SDK's ad loaders from which to request ads.
        val loader = SampleNativeAdLoader(context)
        loader.setAdUnit(serverParameter)

        // Create a native request to give to the SampleNativeAdLoader.
        val request = SampleNativeAdRequest()
        val options = nativeMediationAdRequest.nativeAdOptions
        if (options != null) {
            // If the NativeAdOptions' shouldReturnUrlsForImageAssets is true, the adapter should
            // send just the URLs for the images.
            request.shouldDownloadImages = !options.shouldReturnUrlsForImageAssets()

            // If your network does not support any of the following options, please make sure
            // that it is documented in your adapter's documentation.
            request.setShouldDownloadMultipleImages(options.shouldRequestMultipleImages())
            when (options.imageOrientation) {
                NativeAdOptions.ORIENTATION_LANDSCAPE -> request.setPreferredImageOrientation(
                        SampleNativeAdRequest.IMAGE_ORIENTATION_LANDSCAPE)
                NativeAdOptions.ORIENTATION_PORTRAIT -> request.setPreferredImageOrientation(
                        SampleNativeAdRequest.IMAGE_ORIENTATION_PORTRAIT)
                NativeAdOptions.ORIENTATION_ANY -> request.setPreferredImageOrientation(
                        SampleNativeAdRequest.IMAGE_ORIENTATION_ANY)
                else -> request.setPreferredImageOrientation(SampleNativeAdRequest.IMAGE_ORIENTATION_ANY)
            }
        }

        if (!nativeMediationAdRequest.isUnifiedNativeAdRequested) {
            Log.e(TAG, "Failed to load ad. Request must be for unified native ads.")
            customEventNativeListener.onAdFailedToLoad(AdRequest.ERROR_CODE_INVALID_REQUEST)
            return
        }

        loader.setNativeAdListener(
                SampleCustomNativeEventForwarder(customEventNativeListener, options))

        // Begin a request.
        loader.fetchAd(request)
    }

これは、モック「サンプル SDK」を使って架空の広告ネットワークへのメディエーションを行うサンプル カスタム イベントです。カスタム イベントは、requestNativeAd() のパラメータで提供される情報を使用して SampleNativeAdRequest(サンプル SDK によって提供されるクラス)を構築し、それを使用してサンプル SDK の SampleNativeAdLoader から広告をリクエストします。また、Google Mobile Ads SDK へのイベント返送を処理するために SampleCustomEventNativeForwarder も作成します。

NativeAdOptions

パブリッシャーは、ネイティブ広告のリクエスト作成時に NativeAdOptions オブジェクトを使用して、画像アセットを返す方法などの設定をそのリクエストに関して指定します。カスタム イベントはこれらの設定を踏襲する必要があります。カスタム イベントは、NativeMediationAdRequest オブジェクトで提供される getNativeAdOptions() メソッドを次のように使用して、リクエストの NativeAdOptions オブジェクトを取得します。

Java

    NativeAdOptions options = mediationAdRequest.getNativeAdOptions();
    

Kotlin

    val options = mediationAdRequest.nativeAdOptions
    

NativeAdOptions を取得した後、カスタム イベントはプロパティを読み取り、その設定に従って動作します。たとえば、NativeAdOptionsshouldReturnUrlsForImageAssets 値が false(デフォルト)の場合は、URL ではなく実際の画像アセットを返します。この場合、該当する SDK は画像の URL のみを提供します。カスタム イベントはその URL を使用して画像ファイルをダウンロードし、マッピングされたネイティブ広告でパブリッシャーがそのデータを使用できるようにする必要があります。

Mobile Ads SDK にイベントを転送する

メディエーション対象ネットワークからカスタム イベントがネイティブ広告を読み込もうとするとき、いくつかのことが起こる可能性があります。SDK がネイティブ広告を正常に返したり、エラーを報告したり、使用できる広告がないことを単に報告したりする可能性があります。同様に、ユーザーが広告をタップすると、メディエーション向け SDK がオーバーレイを開いたり、そのアプリから完全に離れて外部ブラウザを開始したりする可能性があります。requestNativeAd() メソッドのパラメータとして CustomEventNativeListener オブジェクトを提供するためには、Google Mobile Ads SDK がこうしたイベントを認識できることが重要です。

カスタム イベントを使って、メディエーション向け SDK からのイベントをリッスンし、それらを適切な CustomEventNativeListener コールバックにマッピングすることもできます。 その場合、カスタム イベントは、次の CustomEventNativeListener コールバックを認識する必要があります。

  • onAdLoaded() - カスタム イベントがネイティブ広告を正常に読み込んだときに、このメソッドが呼び出されます。広告ネットワークの SDK のネイティブ広告を Google Mobile Ads SDK が理解できるオブジェクトにマッピングする UnifiedNativeAdMapper が取得されます。UnifiedNativeAdMapper の作成方法については、ネイティブ広告をマッピングするで説明します。
  • onAdFailedToLoad() - カスタム イベントがネイティブ広告を読み込もうとして失敗した場合、このメソッドを使ってエラーを報告します。その際、単一の整数パラメータが取得され、次のいずれかのエラー定数に設定されます。

  • onAdLeftApplication() - メディエーション向け SDK によって、ユーザーのフォーカスがパブリッシャーのアプリから離れる際(一般的には外部ブラウザを開くとき)にこのメソッドが呼び出されます。

  • onAdOpened() - ユーザーのタップの応答として、インターフェースをカバーするオーバーレイや個別のアクティビティをネイティブ広告が開く場合に、このメソッドが呼び出されます。これには外部ブラウザが含まれており、この場合はカスタム イベントが onAdLeftApplication の直前に onAdOpened を呼び出す必要があります。

  • onAdClosed() - インタフェースをカバーするオーバーレイまたは個別のアクティビティが閉じられた場合、このメソッドを呼び出す必要があります。これは、ネイティブ広告を含むアプリにコントロールが転送されていることを示します。

リスナーは、クリックとインプレッションを、それらをトラッキングするよう選択したカスタム イベントからレポートするメソッドも提供しています(詳しくは、デフォルトのクリック処理とインプレッション記録のオーバーライドをご覧ください)。ひとつはクリックを Google Mobile Ads SDK に伝え、もうひとつはインプレッションを送信します。

  • onAdClicked() - ユーザーがネイティブ広告をクリックしたときに、このメソッドが呼び出されます。
  • onAdImpression() - 同様に、メディエーション向け SDK によって広告のインプレッションが記録されたときに、このメソッドが呼び出されます。

イベントが適切に転送されたことを確認する方法はいくつかありますが、最も簡単なのは、フォワーダとして動作する専用クラスを作成する方法です。 カスタム イベント サンプル プロジェクトには次のクラスがあります。

SampleCustomNativeEventForwarder

Java

    public class SampleCustomNativeEventForwarder extends SampleNativeAdListener {
        private CustomEventNativeListener nativeListener;
        private NativeAdOptions nativeAdOptions;

        public SampleCustomNativeEventForwarder(
                CustomEventNativeListener listener, NativeAdOptions options) {
            this.nativeListener = listener;
            this.nativeAdOptions = options;
        }

        @Override
        public void onNativeAdFetched(SampleNativeAd ad) {
            SampleUnifiedNativeAdMapper mapper =
                    new SampleUnifiedNativeAdMapper(ad, nativeAdOptions);
            nativeListener.onAdLoaded(mapper);
        }

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

Kotlin

    class SampleCustomNativeEventForwarder(
            private val nativeListener: CustomEventNativeListener,
            private val nativeAdOptions: NativeAdOptions) : SampleNativeAdListener() {

        fun onNativeAdFetched(ad: SampleNativeAd) {
            val mapper = SampleUnifiedNativeAdMapper(ad, nativeAdOptions)
            nativeListener.onAdLoaded(mapper)
        }

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

クラスがサンプル SDK の SampleNativeAdListener インターフェースを実装している点にご注目ください。SampleCustomEvent(抜粋)では、このフォワーダ クラスのインスタンスが、setNativeAdListener() メソッドで SampleNativeAdLoader に渡されます。

Java

    loader.setNativeAdListener(new SampleCustomNativeEventForwarder(customEventNativeListener, options));
    

Kotlin

    loader.setNativeAdListener(SampleCustomNativeEventForwarder(customEventNativeListener, options))
    

これによって、サンプル SDK は、報告するイベントがあるときは必ず SampleCustomNativeEventForwarder オブジェクトのリスナー メソッド(onNativeAdFetched()onAdFetchFailed() など)を呼び出すようになります。その後、フォワーダは、Google Mobile Ads SDK の CustomEventNativeListener で適切なメソッドを呼び出して、イベントを転送します。つまり、メディエーション向け SDK をリッスンしているアダプタを Google Mobile Ads SDK がリッスンします。

上述の onAdFetchFailed() メソッドはこの仕組みを示す好例です。広告の読み込みに失敗したサンプル SDK は、フォワーダの onAdFetchFailed() メソッドを呼び出して、エラーコードを渡します。フォワーダはエラーコードを確認し、Google Mobile Ads SDK で使われるいずれかのエラーコードを使って CustomEventNativeListeneronAdFailedToLoad() メソッドを呼び出します。このようにして、サンプル SDK のイベントが Google Mobile Ads SDK のイベントに変換されます。

ネイティブ広告をマッピングする

各種の SDK は、ネイティブ広告向けの固有のフォーマットを独自に備えています。たとえば、「title」フィールドを含むオブジェクトを返すものもあれば、「headline」フィールドを含むものもあります。また、インプレッションのトラッキングとクリックの処理に使用されるメソッドが SDK によって異なることもあります。UnifiedNativeAdMapper によりこうした違いが取り除かれ、メディエーション向け SDK のネイティブ広告オブジェクトが、Google Mobile Ads SDK に求められるインターフェースに合わせて調整されます。カスタム イベントによりこのクラスが拡張され、メディエーション向け SDK に固有の独自のマッパーが作成される必要があります。

サンプル カスタム イベント プロジェクトのサンプル マッパーを次に示します。

SampleUnifiedNativeAdMapper

Java

    public class SampleUnifiedNativeAdMapper extends UnifiedNativeAdMapper {

        private final SampleNativeAd sampleAd;

        public SampleUnifiedNativeAdMapper(SampleNativeAd ad) {
            sampleAd = ad;
            setHeadline(sampleAd.getHeadline());
            setBody(sampleAd.getBody());
            setCallToAction(sampleAd.getCallToAction());
            setStarRating(sampleAd.getStarRating());
            setStore(sampleAd.getStoreName());
            setIcon(new SampleNativeMappedImage(ad.getIcon(), ad.getIconUri(),
                    SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE));
            setAdvertiser(ad.getAdvertiser());

            List<NativeAd.Image> imagesList = new ArrayList<NativeAd.Image>();
            imagesList.add(new SampleNativeMappedImage(ad.getImage(), ad.getImageUri(),
                    SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE));
            setImages(imagesList);

            if (sampleAd.getPrice() != null) {
                NumberFormat formatter = NumberFormat.getCurrencyInstance();
                String priceString = formatter.format(sampleAd.getPrice());
                setPrice(priceString);
            }

            Bundle extras = new Bundle();
            extras.putString(SampleCustomEvent.DEGREE_OF_AWESOMENESS, ad.getDegreeOfAwesomeness());
            this.setExtras(extras);

            setOverrideClickHandling(false);
            setOverrideImpressionRecording(false);

            setAdChoicesContent(sampleAd.getInformationIcon());
        }

        @Override
        public void recordImpression() {
            sampleAd.recordImpression();
        }

        @Override
        public void handleClick(View view) {
            sampleAd.handleClick(view);
        }
    }
    

Kotlin

    class SampleUnifiedNativeAdMapper(private val sampleAd: SampleNativeAd) : UnifiedNativeAdMapper() {

        init {
            headline = sampleAd.headline
            body = sampleAd.body
            callToAction = sampleAd.callToAction
            starRating = sampleAd.starRating
            store = sampleAd.storeName
            icon = SampleNativeMappedImage(sampleAd.icon, sampleAd.iconUri,
                    SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE)
            advertiser = sampleAd.advertiser

            val imagesList = ArrayList<NativeAd.Image>()
            imagesList.add(SampleNativeMappedImage(sampleAd.image, sampleAd.imageUri,
                    SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE))
            images = imagesList

            if (sampleAd.price != null) {
                val formatter = NumberFormat.getCurrencyInstance()
                val priceString = formatter.format(sampleAd.price)
                price = priceString
            }

            val extras = Bundle()
            extras.putString(SampleCustomEvent.DEGREE_OF_AWESOMENESS, sampleAd.degreeOfAwesomeness)
            this.extras = extras

            overrideClickHandling = false
            overrideImpressionRecording = false

            adChoicesContent = sampleAd.informationIcon
        }

        override fun recordImpression() {
            sampleAd.recordImpression()
        }

        override fun handleClick(view: View?) {
            sampleAd.handleClick(view)
        }
    }

まず、コンストラクタ メソッドとその動作の一部について説明します。

メディエーション対象ネイティブ広告オブジェクトへの参照を保持する

コンストラクタは、SampleNativeAd パラメータと NativeAdOptions パラメータを受け入れます。 SampleNativeAd は、ネイティブ広告用にサンプル SDK で使用されるネイティブ広告クラスです。クリック イベントとインプレッション イベントで渡すことができるように、マッパーはメディエーション対象広告への参照を必要とします。NativeAdOptions には、ネイティブ広告に関するパブリッシャーの設定が含まれます。両方のパラメータがローカル変数として保存されます。

マッピングされたアセット プロパティを設定する

コンストラクタは SampleNativeAd オブジェクトを使用して、アセットを UnifiedNativeAdMapper に自動入力します。たとえば、次のコードはメディエーション対象広告の価格データを取得し、そのデータを使って、マッパーの価格を設定します。

Java

    if (sampleAd.getPrice() != null) {
        NumberFormat formatter = NumberFormat.getCurrencyInstance();
        String priceString = formatter.format(sampleAd.getPrice());
        setPrice(priceString);
    }
    

Kotlin

    if (sampleAd.price != null) {
        val formatter = NumberFormat.getCurrencyInstance()
        val priceString = formatter.format(sampleAd.price)
        price = priceString
    }
    

この場合、メディエーション対象広告では価格は double として保存されますが、AdMob では、そのアセットに対して String が使用されます。マッパーは、このような変換の処理を担当します。

画像アセットをマッピングする

画像アセットのマッピングは、doubleString などの単純なデータ型に比べると複雑です。画像が自動的にダウンロードされたり、単に URL 値として返されたりすることがあります。ピクセル密度もさまざまに異なる可能性があります。カスタム イベント デベロッパーがこのような詳細を管理できるように、Google Mobile Ads SDK には NativeAd.Image クラスが用意されています。デベロッパーは、UnifiedNativeAdMapper のサブクラスを作成して、メディエーション対象ネイティブ広告をマッピングする必要がありますが、これと同様に NativeAd.Image のサブクラスを作成して、画像アセットもマッピングする必要があります。

カスタム イベントの SampleNativeMappedImage クラスのコードを次に示します。

Java

    public class SampleNativeMappedImage extends NativeAd.Image {

        private Drawable drawable;
        private Uri imageUri;
        private double scale;

        public SampleNativeMappedImage(Drawable drawable, Uri imageUri, double scale) {
            this.drawable = drawable;
            this.imageUri = imageUri;
            this.scale = scale;
        }

        @Override
        public Drawable getDrawable() {
            return drawable;
        }

        @Override
        public Uri getUri() {
            return imageUri;
        }

        @Override
        public double getScale() {
            return scale;
        }
    }
    

Kotlin

    class SampleNativeMappedImage(private val drawable: Drawable,
                                  private val imageUri: Uri,
                                  private val scale: Double) : NativeAd.Image() {

        override fun getDrawable(): Drawable {
            return drawable
        }

        override fun getUri(): Uri {
            return imageUri
        }

        override fun getScale(): Double {
            return scale
        }
    }
    

SampleUnifiedNativeAdMapper は、マッピングされた画像クラスを次の行で使用して、マッパーのアイコン画像アセットを設定します。

Java

    setIcon(new SampleNativeMappedImage(ad.getAppIcon(), ad.getAppIconUri(),
            SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE));
    

Kotlin

    icon = SampleNativeMappedImage(sampleAd.appIcon, sampleAd.appIconUri,
            SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE)
    

Bundle(extras)にフィールドを追加する

メディエーション向け SDK によっては、AdMob ネイティブ広告フォーマット以外の追加アセットが用意されていることがあります。UnifiedNativeAdMapper クラスには、これらのアセットをパブリッシャーに渡すために使用される setExtras() メソッドが含まれています。SampleUnifiedNativeAdMapper では、これが、サンプル SDK の「degree of awesomeness」アセットに対して使用されます。

Java

    Bundle extras = new Bundle();
    extras.putString(SampleCustomEvent.DEGREE_OF_AWESOMENESS, ad.getDegreeOfAwesomeness());
    this.setExtras(extras);
    

Kotlin

    val extras = Bundle()
    extras.putString(SampleCustomEvent.DEGREE_OF_AWESOMENESS, sampleAd.degreeOfAwesomeness)
    this.extras = extras
    

パブリッシャーは、UnifiedNativeAd クラスの getExtras() メソッドを使用してデータを取得できます。

AdChoices

カスタム イベントは、UnifiedNativeAdMappersetAdChoicesContent() メソッドを経由して AdChoices アイコンを提供する役割を担います。

以下の SampleUnifiedNativeAdMapper のスニペットは、AdChoices アイコンを提供する方法を示します。

Java

    public SampleUnifiedNativeAdMapper(SampleNativeAd ad) {
        ...
        setAdChoicesContent(sampleAd.getInformationIcon());
    }
    

Kotlin

    init {
        ...
        adChoicesContent = sampleAd.informationIcon
    }
    

インプレッション イベントとクリック イベント

Google Mobile Ads SDK とメディエーション向け SDK の両方が、インプレッションまたはクリックがいつ発生したかを知る必要がありますが、このようなイベントをトラッキングする必要があるのはいずれかだけです。カスタム イベントが使用できるアプローチは、メディエーション向け SDK が独自のインプレッションとクリックのトラッキングをサポートしているかどうかに応じて 2 つあります。

handleClick と recordImpression でクリックとインプレッションを処理する

メディエーション向け SDK が独自のトラッキングを行わずにクリックとインプレッションを記録するメソッドを提供している場合に、Google Mobile Ads SDK はこれらのイベントをトラッキングしてアダプタに通知します。UnifiedNativeAdMapper には recordImpression()handleClick() の 2 つのメソッドがあり、カスタム イベントはこれらのメソッドを実装して、メディエーション対象ネイティブ広告オブジェクトの対応メソッドを呼び出します。

SampleUnifiedNativeAdMapper による処理方法を次に示します。

Java

    @Override
    public void recordImpression() {
        sampleAd.recordImpression();
    }

    @Override
    public void handleClick(View view) {
        sampleAd.handleClick(view);
    }
    

Kotlin

    override fun recordImpression() {
        sampleAd.recordImpression()
    }

    override fun handleClick(view: View) {
        sampleAd.handleClick(view)
    }
    

SampleUnifiedNativeAdMapper にはサンプル SDK のネイティブ広告オブジェクトへの参照が保持されるため、そのオブジェクト上の適切なメソッドを呼び出すだけで、クリックまたはインプレッションが報告されます。handleClick() メソッドのパラメータは 1 つであることに注意してください。このパラメータは、クリックを受け取ったネイティブ広告アセットに対応する View オブジェクトです。

デフォルトのクリック処理とインプレッション記録をオーバーライドする

メディエーション向け SDK によっては、独自の方法でクリックとインプレッションをトラッキングした方がよいこともあります。その場合は、UnifiedNativeAdMapper のコンストラクタで次の 2 つの呼び出しを行うことによって、デフォルトのクリックとインプレッションのトラッキングをオーバーライドする必要があります。

Java

    setOverrideClickHandling(true);
    setOverrideImpressionRecording(true);
    

Kotlin

    setOverrideClickHandling(true)
    setOverrideImpressionRecording(true)
    

Mobile Ads SDK にイベントを転送するで説明したように、クリックとインプレッションをトラッキングするカスタム イベントは、onAdClicked() メソッドと onAdImpression() メソッドを介してこれらのイベントを Google Mobile Ads SDK に報告するために必須です。

trackViews() メソッドをオーバーライドし、カスタム イベントを使ってネイティブ広告のビューをメディエーション向け SDK に渡してトラッキングすることも必要です。このアプローチは、カスタム イベントのサンプル プロジェクト(このガイドのコード スニペットの取得元)のサンプル SDK では使用されませんが、仮に使用される場合、カスタム イベントのコードは次のようになります。

Java

    @Override
    public void trackViews(View containerView,
            Map<String, View> clickableAssetViews,
            Map<String, View> nonClickableAssetViews) {
        sampleAd.setNativeAdViewForTracking(containerView);
    }
    

Kotlin


    override fun trackViews(containerView: View?,
            clickableAssetViews: Map<String, View>?,
            nonClickableAssetViews: Map<String, View>?) {
        sampleAd.setNativeAdViewForTracking(containerView)
    }
    

メディエーション向け SDK が個々のアセットのトラッキングをサポートしている場合、clickableAssetViews 内でどのビューをクリック可能にする必要があるかを確認できます。このマップは、 UnifiedNativeAdAssetNames 内の アセット名でキー付けされます。

UnifiedNativeAdMapper には対応する untrackView() メソッドが用意されており、逆の用途に使用されます。つまり、カスタム イベントはこのメソッドをオーバーライドしてビューへの参照をすべて解放し、ネイティブ広告オブジェクトとの関連付けを解除します。

カスタム イベントを使用する

カスタム イベントを使用するには、広告ユニットのメディエーション設定にカスタム イベントを追加します。 これは AdMob 管理画面で行います (広告ユニットのメディエーション設定を編集する詳しい手順については、カスタム イベントの作成に関するヘルプセンター記事をご覧ください)。

カスタム イベントを広告ユニットのメディエーション設定に追加する際は、次の 3 つの情報が必要です。

  • Class Name - カスタム イベントのクラス名です(パッケージ名全体を含む)。
  • Label - AdMob の管理画面で広告ユニットのメディエーション ソースを表示する際に、カスタム イベントを表すのに使用するラベルです。AdMob の管理画面にしか表示されないため、他の誰にも表示されません。
  • Parameter - この広告ユニットがリクエストされたときにカスタム イベントに渡される文字列値です。通常、この値は、メディエーション対象ネットワークからの広告ユニット ID に設定されます。

カスタム イベントのエントリ例のスクリーンショットを次に示します。

これで、AdMob 向けの独自の Android カスタム イベントの記述に必要なものすべてが準備できました。