原生廣告自訂事件

必要條件

完成自訂事件設定。

請求原生廣告

當瀑布式中介服務鏈中出現自訂事件廣告空間時，系統會對您建立自訂事件時提供的類別名稱呼叫 loadNativeAd() 方法。在本例中，該方法位於 SampleCustomEvent 中，然後呼叫 SampleNativeCustomEventLoader 中的 loadNativeAd() 方法。

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

在我們的自訂事件範例中，SampleCustomEvent 會擴充 Adapter 類別，然後委派給 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 類別。

  • 接收廣告事件回呼並向 Google Mobile Ads SDK 傳送報表。

在 AdMob 使用者介面中定義的選用參數會納入廣告設定。參數可透過 adConfiguration.getServerParameters().getString(MediationConfiguration.CUSTOM_EVENT_SERVER_PARAMETER_FIELD) 存取。這個參數通常是廣告單元 ID，廣告聯播網 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 回呼中實作。以這個範例來說，Sample 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 負責調解這些差異，並調整中介服務 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 參數，也就是 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 的「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 都需要知道何時發生曝光或點擊，但只有一個 SDK 需要追蹤這些事件。自訂事件可採用兩種不同的方法，視中介服務 SDK 是否支援自行追蹤曝光和點擊而定。

使用 Google Mobile Ads SDK 追蹤點擊和曝光次數

如果中介服務 SDK 不會自行追蹤曝光和點擊，但提供記錄點擊和曝光的方法，Google Mobile Ads SDK 就能追蹤這些事件並通知轉接程式。UnifiedNativeAdMapper 類別包含兩種方法：recordImpression() 和 handleClick()，自訂事件可實作這些方法，在經過中介服務的原生廣告物件上呼叫對應的方法：

Java

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

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

由於 SampleNativeAdMapper 參照了 Sample 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 上查看完整範例。