原生廣告自訂事件

必要條件

完成自訂事件設定。

請求原生廣告

到達刊登序列中介服務鏈中的自訂事件委刊項時， 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 的廣告事件回呼。

在 Ad Manager 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，而 Ad Manager 對相同的素材資源使用 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 會提供額外素材資源， Ad Manager 原生廣告格式UnifiedNativeAdMapper 類別包含 setExtras() 方法，可用來將這些資產傳遞至 發布商。SampleNativeAdMapper 會將此用於範例 SDK 的 「出色度」資產：

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。