必要條件
完成自訂事件設定。
請求原生廣告
當刊登序列中介服務鏈中到達自訂事件委刊項時,系統會使用您在建立自訂事件時提供的類別名稱呼叫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 的廣告事件回呼
廣告設定包含 AdMob UI 中定義的選用參數。您可以透過 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()
。藉由傳入實作 MediationNativeAd
的類別執行個體來呼叫 onSuccess()
。
一般來說,這些方法是在轉接程式實作的第三方 SDK 回呼內實作。在這個範例中,範例 SDK 的 SampleAdListener
含有相關回呼:
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
會負責協調這些差異,並根據 Google Mobile Ads SDK 預期的介面調整中介服務 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
參數,這是 Sample 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
) 較為複雜。系統可能會自動下載圖片,或以網址值的形式傳回圖片。他們的像素轉 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));
在額外套件中新增欄位
有些中介服務 SDK 會提供AdMob 原生廣告格式以外的素材資源,UnifiedNativeAdMapper
類別包含 setExtras()
方法,可用於將這些資產傳遞給發布者。SampleNativeAdMapper
會將此元素用於 Sample SDK 的「很棒的程度」素材資源:
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 都必須知道曝光或點擊何時發生,但只需要一個 SDK 就能追蹤這些事件。自訂事件可採用兩種不同方法,具體視中介 SDK 是否支援自行追蹤曝光和點擊的方式而定。
使用 Google Mobile Ads SDK 追蹤點擊和曝光
如果中介服務 SDK 不會自行執行曝光和點擊追蹤,但提供記錄點擊和曝光的方法,Google Mobile Ads SDK 就能追蹤這些事件並通知轉接程式。UnifiedNativeAdMapper
interface 包含兩種方法:recordImpression()
以及 handleClick()
自訂事件可實作,用於在中介原生廣告物件呼叫相應的方法:
Java
@Override public void recordImpression() { sampleAd.recordImpression(); } @Override public void handleClick(View view) { sampleAd.handleClick(view); }
由於 SampleNativeAdMapper
會保留對範例 SDK 的原生廣告物件的參照,因此可針對該物件呼叫適當的方法,以回報點擊或曝光。請注意, handleClick()
方法使用單一參數:與接收點擊的原生廣告素材資源相對應的 View
物件。
使用中介服務 SDK 追蹤點擊和曝光
有些採用中介服務的 SDK 可能會想自行追蹤點擊和曝光次數,在此情況下,您應該在 UnifiedNativeAdMapper
的建構函式中進行下列兩項呼叫,藉此覆寫預設點擊和曝光追蹤:
Java
setOverrideClickHandling(true); setOverrideImpressionRecording(true);
必須覆寫點擊和曝光追蹤的自訂事件,才能向 Google Mobile Ads SDK 回報 onAdClicked()
和 onAdImpression()
事件。
如要追蹤曝光和點擊,中介服務 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 取得完整範例。