Пользовательские события нативной рекламы

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

Предварительные требования

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

Запросить нативную рекламу

Когда в цепочке обработки событий «водопад» достигается элемент пользовательского события, вызывается метод 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 .

  • Получение и передача обратных вызовов событий рекламы в SDK Google Mobile Ads.

Необязательный параметр, определенный в пользовательском интерфейсе 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 для работы с интерфейсом, ожидаемым SDK Google Mobile Ads. Пользовательские события должны расширять этот класс, чтобы создавать собственные мапперы, специфичные для их 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. Масштаб их пикселей в 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:

Java 

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

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

AdChoices

Ваше пользовательское событие отвечает за отображение значка AdChoices с помощью метода setAdChoicesContent() в UnifiedNativeAdMapper . Вот фрагмент кода из 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);

Для отправки событий onAdClicked() и onAdImpression() в SDK Google Mobile Ads необходимы пользовательские события, которые переопределяют отслеживание кликов и показов.

Для отслеживания показов и кликов 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() , который пользовательские события могут переопределить, чтобы освободить все ссылки на представление и отделить его от объекта нативной рекламы.

Пересылайте события медиации в SDK Google Mobile Ads

Все поддерживаемые механизмом медиации функции обратного вызова можно найти в документации MediationNativeAdCallback .

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

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