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

Выберите платформу: 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) обратных вызовов событий, связанных с рекламой.

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

Как добавить поля в пакет extras Bundle

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

Как отслеживать клики и показы с помощью SDK для медиации

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

Java

setOverrideClickHandling(true);
setOverrideImpressionRecording(true);

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

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