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

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

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

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

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

Чтобы запросить нативное объявление, создайте или измените класс, который расширяет Adapter для реализации loadNativeAd() . Если класс, расширяющий Adapter , уже существует, реализуйте там loadNativeAd() . Кроме того, создайте новый класс для реализации UnifiedNativeAdMapper .

В нашем примере пользовательского события SampleCustomEvent расширяет класс Adapter , а затем делегирует его SampleNativeCustomEventLoader .

Ява 

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.

Необязательный параметр, определенный в пользовательском интерфейсе Менеджера рекламы, включается в конфигурацию объявления. Доступ к параметру можно получить через adConfiguration.getServerParameters().getString(MediationConfiguration.CUSTOM_EVENT_SERVER_PARAMETER_FIELD) . Обычно этот параметр представляет собой идентификатор рекламного блока, который требуется SDK рекламной сети при создании экземпляра рекламного объекта.

Ява 

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 с соответствующими обратными вызовами:

Ява 

@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 имеют свои уникальные форматы нативной рекламы. Например, один может возвращать объекты, содержащие поле «заголовок», а другой — «заголовок». Кроме того, методы, используемые для отслеживания показов и обработки кликов, могут различаться в зависимости от SDK.

UnifiedNativeAdMapper отвечает за устранение этих различий и адаптацию нативного рекламного объекта опосредованного SDK для соответствия интерфейсу, ожидаемому Google Mobile Ads SDK. Пользовательские события должны расширять этот класс для создания собственных картографов, специфичных для их опосредованного SDK. Вот пример преобразователя рекламы из нашего примера проекта специального мероприятия:

Ява 

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 .

Этот фрагмент получает данные о цене опосредованной рекламы и использует их для установки цены картографа:

Ява 

if (sampleAd.getPrice() != null) {
    NumberFormat formatter = NumberFormat.getCurrencyInstance();
    String priceString = formatter.format(sampleAd.getPrice());
    setPrice(priceString);
}

В этом примере в объявлении с посредником цена сохраняется как double , а Менеджер рекламы использует String для того же актива. Сопоставитель отвечает за обработку этих типов преобразований.

Ресурсы изображения карты

Сопоставление ресурсов изображений сложнее, чем сопоставление типов данных, таких как double или String . Изображения могут загружаться автоматически или возвращаться в виде значений URL. Их масштабы пикселей на дюйм также могут различаться.

Чтобы помочь вам управлять этими деталями, Google Mobile Ads SDK предоставляет класс NativeAd.Image . Во многом так же, как вам необходимо создать подкласс UnifiedNativeAdMapper для сопоставления нативной рекламы с посредником, вам также следует создать подкласс NativeAd.Image при сопоставлении графических ресурсов.

Вот пример класса SampleNativeMappedImage пользовательского события:

Ява 

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 использует свой сопоставленный класс изображения в этой строке, чтобы установить ресурс изображения значка преобразователя:

Ява 

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

Добавьте поля в пакет дополнительных услуг

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

Ява 

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

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

Выбор рекламы

Ваше пользовательское событие отвечает за предоставление значка AdChoices с помощью метода setAdChoicesContent() в UnifiedNativeAdMapper . Вот фрагмент из SampleNativeAdMapper показывающий, как предоставить значок AdChoices:

Ява 

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

Ява 

@Override
public void recordImpression() {
  sampleAd.recordImpression();
}

@Override
public void handleClick(View view) {
  sampleAd.handleClick(view);
}

Поскольку SampleNativeAdMapper содержит ссылку на собственный рекламный объект Sample SDK, он может вызвать соответствующий метод этого объекта, чтобы сообщить о клике или показе. Обратите внимание, что метод handleClick() принимает один параметр: объект View , соответствующий ресурсу нативного объявления, получившему клик.

Отслеживайте клики и показы с помощью медиированного SDK

Некоторые опосредованные SDK могут предпочесть отслеживать клики и показы самостоятельно. В этом случае вам следует переопределить отслеживание кликов и показов по умолчанию, выполнив следующие два вызова в конструкторе вашего UnifiedNativeAdMapper :

Ява 

setOverrideClickHandling(true);
setOverrideImpressionRecording(true);

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

Для отслеживания показов и кликов опосредованному SDK, вероятно, потребуется доступ к представлениям, чтобы включить отслеживание. Пользовательское событие должно переопределить метод trackViews() и использовать его для передачи представления собственного объявления в промежуточный SDK для отслеживания. Пример SDK из нашего проекта примера пользовательского события (из которого взяты фрагменты кода этого руководства) не использует этот подход; но если бы это было так, код пользовательского события выглядел бы примерно так:

Ява 

@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 Mobile Ads SDK. Вот пример использования обратных вызовов:

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