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

Выберите платформу: 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.

Необязательный параметр, определенный в пользовательском интерфейсе Ad Manager, включается в конфигурацию объявления. Доступ к параметру можно получить через 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 ), тогда как в Ad Manager для этого же параметра используется 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, использующие посредников, предоставляют дополнительные ресурсы помимо тех, что есть в нативном формате рекламы Ad Manager. Класс 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 .