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