原生廣告自訂事件

必要條件

完成自訂事件設定。

請求原生廣告

當刊登序列中介服務鏈中到達自訂事件委刊項時，系統會使用您在建立自訂事件時提供的類別名稱呼叫the loadNativeAd() method 。在此情況下，該方法位於 SampleCustomEvent 中，接著在 SampleNativeCustomEventLoader中呼叫the loadNativeAd() method 。

如要請求原生廣告，請建立或修改可擴充 Adapter 的類別，以導入 loadNativeAd()。如果擴充 Adapter 的類別已存在，請在其中實作 loadNativeAd()。此外，您也可以建立新類別來實作 UnifiedNativeAdMapper。

在自訂事件範例中，SampleCustomEvent 會實作the Adapter interface ，然後委派給SampleNativeCustomEventLoader。

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。

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 含有相關回呼：

@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 專屬的對應程式。以下是自訂事件專案範例的廣告對應工具：

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 中的資產。

這段程式碼會取得中介服務廣告的價格資料，並據此設定對應者的價格：

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 類別範例：

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 會在這一行中使用其對應的圖片類別，設定對應程式的圖示圖片素材資源：

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

在額外套件中新增欄位

有些中介服務 SDK 會提供AdMob 原生廣告格式以外的素材資源，UnifiedNativeAdMapper 類別包含 setExtras() 方法，可用於將這些資產傳遞給發布者。SampleNativeAdMapper 會將此元素用於 Sample SDK 的「很棒的程度」素材資源：

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

發布者可以使用 NativeAd 類別的 getExtras() 方法擷取資料。

AdChoices

您的自訂事件負責使用 UnifiedNativeAdMapper 上的 setAdChoicesContent() 方法提供 AdChoices 圖示。以下 SampleNativeAdMapper 程式碼片段說明如何提供 AdChoices 圖示：

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() 自訂事件可實作，用於在中介原生廣告物件呼叫相應的方法：

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

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

由於 SampleNativeAdMapper 會保留對範例 SDK 的原生廣告物件的參照，因此可針對該物件呼叫適當的方法，以回報點擊或曝光。請注意， handleClick() 方法使用單一參數：與接收點擊的原生廣告素材資源相對應的 View 物件。

使用中介服務 SDK 追蹤點擊和曝光

有些採用中介服務的 SDK 可能會想自行追蹤點擊和曝光次數，在此情況下，您應該在 UnifiedNativeAdMapper 的建構函式中進行下列兩項呼叫，藉此覆寫預設點擊和曝光追蹤：

setOverrideClickHandling(true);
setOverrideImpressionRecording(true);

必須覆寫點擊和曝光追蹤的自訂事件，才能向 Google Mobile Ads SDK 回報 onAdClicked() 和 onAdImpression() 事件。

如要追蹤曝光和點擊，中介服務 SDK 可能需要存取檢視畫面，才能啟用追蹤功能。自訂事件應覆寫 trackViews() 方法，並使用此方法將原生廣告的檢視畫面傳送至中介 SDK 追蹤。自訂事件範例專案中的 SDK 範例 (這是本指南的程式碼片段已經擷取而來) 並未使用這個方法，但如果使用的話，自訂事件程式碼看起來會像這樣：

@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 取得完整範例。