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

Предпосылки

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

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

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

Необязательный параметр, определенный в пользовательском интерфейсе AdMob, включен в конфигурацию объявления. Параметр можно получить через 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 имеют свои собственные уникальные форматы для нативной рекламы. Один может возвращать объекты, содержащие поле «title», например, а другой может иметь «headline». Кроме того, методы, используемые для отслеживания показов и обработки кликов, могут различаться в разных 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 для своих нативных объявлений. Mapper нуждается в ссылке на опосредованную рекламу, чтобы он мог передавать события клика и показа. SampleNativeAd хранится как локальная переменная.

Установить свойства сопоставленных активов

Конструктор использует объект SampleNativeAd для заполнения ресурсов в UnifiedNativeAdMapper .

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

Ява 

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

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

Активы изображения карты

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

Чтобы помочь вам управлять этими деталями, 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 предоставляют дополнительные активы помимо тех, что есть в формате нативной рекламы AdMob. Класс UnifiedNativeAdMapper включает метод setExtras() , который используется для передачи этих активов издателям. SampleNativeAdMapper использует это для актива Sample SDK "степень крутости":

Ява 

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

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

AdChoices

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

Ява 

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

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

И Google Mobile Ads SDK, и mediated SDK должны знать, когда происходит показ или клик, но только один SDK должен отслеживать эти события. Существует два разных подхода, которые могут использовать пользовательские события, в зависимости от того, поддерживает ли mediated 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 .