Специальные события для нативных объявлений

Выберите платформу: Android iOS Android (устаревшая версия)

Требования

Завершите настройку специальных событий.

Как запросить нативное объявление

Когда в цепочке каскадной медиации доходит очередь до позиции специального события, вызывается метод loadNativeAd() для класса, название которого вы указали при создании специального события. В данном случае этот метод находится в SampleCustomEvent, который затем вызывает метод loadNativeAd() в SampleNativeCustomEventLoader.

Чтобы запросить нативное объявление, создайте или измените класс, расширяющий 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 (Legacy) обратных вызовов, связанных с событиями объявлений.

Необязательный параметр, заданный в интерфейсе AdMob, включен в конфигурацию объявления. Доступ к параметру можно получить через adConfiguration.getServerParameters().getString(MediationConfiguration.CUSTOM_EVENT_SERVER_PARAMETER_FIELD). Обычно это идентификатор рекламного блока, который требуется 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(). 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 (Legacy). Специальные события должны расширять этот класс, чтобы создавать собственные сопоставители, относящиеся к их 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. Изображения могут скачиваться автоматически или возвращаться в виде URL. Соотношение пикселей и точек на дюйм также может быть разным.

Для управления этими данными в Google Mobile Ads SDK (Legacy) предусмотрен класс 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));

Добавьте поля в объект Bundle extras

Некоторые SDK для медиации предоставляют дополнительные объекты, помимо тех, которые входят в формат нативного объявления AdMob. Класс UnifiedNativeAdMapper включает метод setExtras(), который используется для передачи этих объектов издателям. В SampleNativeAdMapper это используется для объекта "степень крутости" в Sample SDK:

Java

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

Издатели могут получить данные с помощью метода getExtras() класса NativeAd.

AdChoices

Специальное событие должно предоставлять значок "Выбор рекламы" с помощью метода setAdChoicesContent() в UnifiedNativeAdMapper. Ниже приведен фрагмент кода из файла SampleNativeAdMapper, в котором показано, как добавить значок "Выбор рекламы".

Java

public SampleNativeAdMapper(SampleNativeAd ad) {
    ...
    setAdChoicesContent(sampleAd.getInformationIcon());
}

События показов и кликов

И Google Mobile Ads SDK (Legacy), и SDK, используемый для медиации, должны знать, когда происходит показ или клик, но отслеживать эти события должен только один SDK. Существует два подхода к использованию специальных событий в зависимости от того, поддерживает ли SDK, используемый для медиации, отслеживание показов и кликов.

Отслеживайте клики и показы с помощью Google Mobile Ads SDK (Legacy)

Если SDK, используемый для медиации, не отслеживает показы и клики, но предоставляет методы для их регистрации, Google Mobile Ads SDK (Legacy) может отслеживать эти события и уведомлять адаптер. Класс 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);

Специальные события, которые переопределяют отслеживание кликов и показов, должны передавать события onAdClicked() и onAdImpression() в Google Mobile Ads 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 (Legacy)

Все поддерживаемые обратные вызовы перечислены в документации по MediationNativeAdCallback.

Важно, чтобы ваше специальное событие пересылало как можно больше таких обратных вызовов, чтобы ваше приложение получало эти эквивалентные события от Google Mobile Ads SDK (Legacy). Пример использования обратных вызовов:

На этом реализация специальных событий для нативных объявлений завершена. Полный пример доступен на GitHub.