原生廣告自訂事件

必要條件

完成自訂事件設定。

請求原生廣告

當刊登序列中介服務鏈執行到自訂事件委刊項，系統會以您在建立自訂事件時指定的類別名稱，呼叫 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 UI 中定義的選用參數會包含在廣告設定，使用 adConfiguration.getServerParameters().getString(MediationConfiguration.CUSTOM_EVENT_SERVER_PARAMETER_FIELD) 即可存取。這項參數通常是廣告單元 ID，廣告聯播網 SDK 在例項化廣告物件時會用到。

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 負責解決這些差異，並調整中介服務 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 等資料類型，對應圖片資產會比較複雜。圖片可能會自動下載，或以網址值形式傳回，像素與 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 則利用這個方法，傳遞範例 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 保留範例 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。