原生廣告自訂事件

必要條件

完成自訂事件設定。

要求原生廣告

到達刊登序列中介服務鏈中的自訂事件委刊項時， 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) 存取此參數。這個參數通常是廣告聯播網 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：

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 等資料類型更為複雜。Google 可能會自動下載圖片，或 以網址值的形式傳回他們的像素與 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 會使用這一行中對應的圖片類別來設定 Mapper 的圖示圖片資產：

Java

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

在 extras 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() 方法。以下是 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 行動服務回報 onAdClicked() 和 onAdImpression() 事件 廣告 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 Play 遊戲收到這些對等事件 Mobile Ads SDK以下是使用回呼的範例：

如此就能完成原生廣告的自訂事件導入。您可以在 GitHub 上取得完整範例。