前提条件
カスタム イベントの設定を完了します。
ネイティブ広告をリクエストする
ウォーターフォール メディエーション チェーンでカスタム イベント広告申込情報に達すると、カスタム イベントの作成時に指定したクラス名でthe loadNativeAd()
method が呼び出されます。この場合、このメソッドは SampleCustomEvent
にあり、 SampleNativeCustomEventLoader
のthe loadNativeAd()
method を呼び出します。
ネイティブ広告をリクエストするには、Adapter
を拡張して loadNativeAd()
を実装するクラスを作成または変更します。Adapter
を拡張するクラスがすでに存在する場合は、そこに loadNativeAd()
を実装します。さらに、UnifiedNativeAdMapper
を実装する新しいクラスを作成します。
このカスタム イベントの例では、SampleCustomEvent
がthe Adapter
interface を実装し、SampleNativeCustomEventLoader
にデリゲートしています。
Java
package com.google.ads.mediation.sample.customevent; import com.google.android.gms.ads.mediation.Adapter; import com.google.android.gms.ads.mediation.MediationAdConfiguration; import com.google.android.gms.ads.mediation.MediationAdLoadCallback; import com.google.android.gms.ads.mediation.MediationNativeAdCallback; ... public class SampleCustomEvent extends Adapter { private SampleNativeCustomEventLoader nativeLoader; @Override public void loadNativeAd( @NonNull MediationNativeAdConfiguration adConfiguration, @NonNull MediationAdLoadCallback<UnifiedNativeAdMapper, MediationNativeAdCallback> callback) { nativeLoader = new SampleNativeCustomEventLoader(adConfiguration, callback); nativeLoader.loadAd(); } }
SampleNativeCustomEventLoader
は次のタスクを担当します。
ネイティブ広告を読み込む
UnifiedNativeAdMapper
interfaceの実装広告イベント コールバックを受信して Google Mobile Ads SDK に報告する
UI で定義されたオプション パラメータは、 AdMob 広告設定に含まれます。このパラメータには adConfiguration.getServerParameters().getString(MediationConfiguration.CUSTOM_EVENT_SERVER_PARAMETER_FIELD)
からアクセスできます。このパラメータは通常、広告ネットワーク SDK が広告オブジェクトをインスタンス化する際に必要とする広告ユニット ID です。
Java
package com.google.ads.mediation.sample.customevent; import com.google.android.gms.ads.mediation.Adapter; import com.google.android.gms.ads.mediation.MediationNativeAdConfiguration; import com.google.android.gms.ads.mediation.MediationAdLoadCallback; import com.google.android.gms.ads.mediation.MediationNativeAdCallback; ... public class SampleNativeCustomEventLoader extends SampleNativeAdListener { /** Configuration for requesting the native ad from the third-party network. */ private final MediationNativeAdConfiguration mediationNativeAdConfiguration; /** Callback that fires on loading success or failure. */ private final MediationAdLoadCallback<UnifiedNativeAdMapper, MediationNativeAdCallback> mediationAdLoadCallback; /** Callback for native ad events. */ private MediationNativeAdCallback nativeAdCallback; /** Constructor */ public SampleNativeCustomEventLoader( @NonNull MediationNativeAdConfiguration mediationNativeAdConfiguration, @NonNull MediationAdLoadCallback<MediationNativeAd, MediationNativeAdCallback> mediationAdLoadCallback) { this.mediationNativeAdConfiguration = mediationNativeAdConfiguration; this.mediationAdLoadCallback = mediationAdLoadCallback; } /** Loads the native ad from the third-party ad network. */ public void loadAd() { // Create one of the Sample SDK's ad loaders to request ads. Log.i("NativeCustomEvent", "Begin loading native ad."); SampleNativeAdLoader loader = new SampleNativeAdLoader(mediationNativeAdConfiguration.getContext()); // All custom events have a server parameter named "parameter" that returns // back the parameter entered into the UI when defining the custom event. String serverParameter = mediationNativeAdConfiguration .getServerParameters() .getString(MediationConfiguration .CUSTOM_EVENT_SERVER_PARAMETER_FIELD); Log.d("NativeCustomEvent", "Received server parameter."); loader.setAdUnit(serverParameter); // Create a native request to give to the SampleNativeAdLoader. SampleNativeAdRequest request = new SampleNativeAdRequest(); NativeAdOptions options = mediationNativeAdConfiguration.getNativeAdOptions(); if (options != null) { // If the NativeAdOptions' shouldReturnUrlsForImageAssets is true, the adapter should // send just the URLs for the images. request.setShouldDownloadImages(!options.shouldReturnUrlsForImageAssets()); request.setShouldDownloadMultipleImages(options.shouldRequestMultipleImages()); switch (options.getMediaAspectRatio()) { case NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_LANDSCAPE: request.setPreferredImageOrientation(SampleNativeAdRequest.IMAGE_ORIENTATION_LANDSCAPE); break; case NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_PORTRAIT: request.setPreferredImageOrientation(SampleNativeAdRequest.IMAGE_ORIENTATION_PORTRAIT); break; case NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_SQUARE: case NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_ANY: case NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_UNKNOWN: default: request.setPreferredImageOrientation(SampleNativeAdRequest.IMAGE_ORIENTATION_ANY); } } loader.setNativeAdListener(this); // Begin a request. Log.i("NativeCustomEvent", "Start fetching native ad."); loader.fetchAd(request); } }
広告が正常に取得されたか、エラーが発生したかに応じて、onSuccess()
または onFailure()
を呼び出します。onSuccess()
は、MediationNativeAd
を実装するクラスのインスタンスを渡すことで呼び出されます。
通常、これらのメソッドは、アダプタが実装するサードパーティ SDK のコールバック内に実装されます。この例では、関連するコールバックを含む SampleAdListener
がサンプル SDK に含まれています。
Java
@Override public void onNativeAdFetched(SampleNativeAd ad) { SampleUnifiedNativeAdMapper mapper = new SampleUnifiedNativeAdMapper(ad); mediationNativeAdCallback = mediationAdLoadCallback.onSuccess(mapper); } @Override public void onAdFetchFailed(SampleErrorCode errorCode) { mediationAdLoadCallback.onFailure(SampleCustomEventError.createSampleSdkError(errorCode)); }
ネイティブ広告をマッピングする
SDK ごとに、ネイティブ広告用の独自のフォーマットがあります。たとえば、「title」フィールドを含むオブジェクトを返すものもあれば、「headline」フィールドを含むオブジェクトを返すものもあります。また、インプレッションのトラッキングとクリックの処理に使用されるメソッドが SDK によって異なる場合があります。
UnifiedNativeAdMapper
は、こうした違いを調整し、メディエーション向け SDK のネイティブ広告オブジェクトを、Google Mobile Ads SDK に求められるインターフェースに適合するように適応させます。カスタム イベントでは、このクラスを拡張して、メディエーションされる SDK に固有の独自のマッパーを作成する必要があります。サンプル カスタム イベント プロジェクトの広告マッパーの例を次に示します。
Java
package com.google.ads.mediation.sample.customevent; import com.google.android.gms.ads.mediation.UnifiedNativeAdMapper; import com.google.android.gms.ads.nativead.NativeAd; ... 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); } // The Sample SDK doesn't do its own impression/click tracking, instead relies on its // publishers calling the recordImpression and handleClick methods on its native ad object. So // there's no need to pass a reference to the View being used to display the native ad. If // your mediated network does need a reference to the view, the following method can be used // to provide one. @Override public void trackViews(View containerView, Map<String, View> clickableAssetViews, Map<String, View> nonClickableAssetViews) { super.trackViews(containerView, clickableAssetViews, nonClickableAssetViews); // If your ad network SDK does its own impression tracking, here is where you can track the // top level native ad view and its individual asset views. } @Override public void untrackView(View view) { super.untrackView(view); // Here you would remove any trackers from the View added in trackView. } }
では、コンストラクタ コードを詳しく見てみましょう。
メディエーションされるネイティブ広告オブジェクトへの参照を保持する
コンストラクタは SampleNativeAd
パラメータを受け取ります。このパラメータは、ネイティブ広告用にサンプル SDK で使用されるネイティブ広告クラスです。クリック イベントとインプレッション イベントを渡すために、マッパーはメディエーション対象広告への参照を必要とします。SampleNativeAd
はローカル変数として格納されます。
マッピングされたアセット プロパティを設定する
コンストラクタは、SampleNativeAd
オブジェクトを使用して UnifiedNativeAdMapper
にアセットを設定します。
次のスニペットは、メディエーション対象広告の価格データを取得し、そのデータを使用してマッパーの価格を設定します。
Java
if (sampleAd.getPrice() != null) { NumberFormat formatter = NumberFormat.getCurrencyInstance(); String priceString = formatter.format(sampleAd.getPrice()); setPrice(priceString); }
この例では、メディエーション対象広告では価格は double
として保存されますが、AdMob は同じアセットに対して String
を使用しています。マッパーは、このような変換の処理を担当します。
画像アセットをマッピングする
画像アセットのマッピングは、double
や String
などのデータ型のマッピングよりも複雑です。画像は自動的にダウンロードされるか、URL 値として返されます。ピクセル対 dpi のスケールもさまざまです。
こうした詳細情報を管理しやすくするために、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; } }
SampleNativeAdMapper
はマッピングされた画像クラスを次の行で使用して、マッパーのアイコン画像アセットを設定します。
Java
setIcon(new SampleNativeMappedImage(ad.getAppIcon(), ad.getAppIconUri(), SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE));
エクストラ Bundle にフィールドを追加する
メディエーション向け SDK の中には、ネイティブ広告フォーマット以外の追加アセットを提供するものもあります。AdMob UnifiedNativeAdMapper
クラスには、これらのアセットをパブリッシャーに渡すために使用される setExtras()
メソッドが含まれています。SampleNativeAdMapper
は、これをサンプル SDK の「degree of Awesomeness」アセットに使用します。
Java
Bundle extras = new Bundle(); extras.putString(SampleCustomEvent.DEGREE_OF_AWESOMENESS, ad.getDegreeOfAwesomeness()); this.setExtras(extras);
パブリッシャーは、NativeAd
クラスの getExtras()
メソッドを使用してデータを取得できます。
AdChoices
カスタム イベントは、UnifiedNativeAdMapper
の setAdChoicesContent()
メソッドを使用して AdChoices アイコンを提供します。以下の SampleNativeAdMapper
のスニペットは、AdChoices アイコンを提供する方法を示しています。
Java
public SampleNativeAdMapper(SampleNativeAd ad) { ... setAdChoicesContent(sampleAd.getInformationIcon()); }
インプレッション イベントとクリック イベント
Google Mobile Ads SDK とメディエーション向け SDK の両方がインプレッションまたはクリックの発生タイミングを認識する必要がありますが、これらのイベントをトラッキングする必要があるのは 1 つの SDK のみです。カスタム イベントで使用できるアプローチは 2 種類あり、メディエーションされる SDK がインプレッションとクリックの独自のトラッキングをサポートしているかどうかに応じて異なります。
Google Mobile Ads SDK を使ってクリックとインプレッションをトラッキングする
メディエーション向け SDK が独自にインプレッションとクリックのトラッキングを実行せず、クリックとインプレッションを記録するメソッドを提供している場合、Google Mobile Ads SDK はこれらのイベントをトラッキングしてアダプタに通知できます。UnifiedNativeAdMapper
interface にはrecordImpression()
と handleClick()
の 2 つのメソッドがあり、カスタム イベントは、メディエーション対象ネイティブ広告オブジェクト上の対応するメソッドを呼び出すために実装できます。
Java
@Override public void recordImpression() { sampleAd.recordImpression(); } @Override public void handleClick(View view) { sampleAd.handleClick(view); }
SampleNativeAdMapper
はサンプル SDK のネイティブ広告オブジェクトへの参照を保持しているため、そのオブジェクト上の適切なメソッドを呼び出して、クリックまたはインプレッションを報告できます。 handleClick()
メソッドは単一のパラメータ(クリックを受け取ったネイティブ広告アセットに対応する View
オブジェクト)を受け取ります。
メディエーション向け SDK でクリックとインプレッションをトラッキングする
メディエーション向け SDK によっては、クリックとインプレッションを独自にトラッキングすることをおすすめします。その場合は、UnifiedNativeAdMapper
のコンストラクタで次の 2 つの呼び出しを行って、デフォルトのクリックおよびインプレッション トラッキングをオーバーライドする必要があります。
Java
setOverrideClickHandling(true); setOverrideImpressionRecording(true);
クリックとインプレッションのトラッキングをオーバーライドするカスタム イベントは、onAdClicked()
イベントと onAdImpression()
イベントを Google Mobile Ads SDK にレポートするために必要です。
インプレッションやクリックをトラッキングする場合、メディエーション向け SDK がビューにアクセスしてトラッキングを有効にする必要があると考えられます。カスタム イベントでは trackViews()
メソッドをオーバーライドし、それを使ってネイティブ広告のビューをメディエーション向け SDK に渡してトラッキングする必要があります。(このガイドのコード スニペットの取得元の)カスタム イベント サンプル プロジェクトのサンプル SDK では、このアプローチは使用されませんが、使用する場合、カスタム イベント コードは次のようになります。
Java
@Override public void trackViews(View containerView, Map<String, View> clickableAssetViews, Map<String, View> nonClickableAssetViews) { sampleAd.setNativeAdViewForTracking(containerView); }
メディエーション向け SDK が個々のアセットのトラッキングをサポートしている場合、clickableAssetViews
内でどのビューをクリック可能にする必要があるかを確認できます。このマップは、NativeAdAssetNames
のアセット名をキーとしています。UnifiedNativeAdMapper
には対応する untrackView()
メソッドが用意されています。カスタム イベントはこのメソッドをオーバーライドして、ビューへの参照をすべて解放し、ネイティブ広告オブジェクトとの関連付けを解除します。
メディエーション イベントを Google Mobile Ads SDK に転送する
メディエーションがサポートするすべてのコールバックについては、MediationNativeAdCallback
のドキュメントをご覧ください。
アプリが Google Mobile Ads SDK から同等のイベントを受け取れるように、カスタム イベントでこれらのコールバックをできるだけ多く転送することが重要です。以下に、コールバックの使用例を示します。
これで、ネイティブ広告のカスタム イベントの実装が完了しました。完全なサンプルは GitHub で入手できます。