Адаптивный sticky-баннер
Адаптивный sticky-баннер — небольшое, автоматически обновляемое рекламное объявление, которое располагается внизу или вверху экрана приложения. Баннер не перекрывает основной контент приложения и часто используется в приложениях-играх.
Адаптивный sticky-баннер обеспечивает максимальную эффективность за счет оптимизации размера рекламы для каждого устройства. Данный тип рекламы позволяет разработчикам указывать максимально допустимую ширину объявления, при этом наиболее оптимальный размер рекламы определяется автоматически. Высота адаптивного sticky-баннера не будет превышать 15% высоты экрана.
Это руководство покажет, как интегрировать адаптивный sticky-баннер в Android‐приложение. В дополнение к примерам кода и инструкции оно содержит рекомендации по использованию данного формата рекламы, а также ссылки на дополнительные ресурсы.
Дополнительно об интеграции адаптивного sticky-баннера смотрите в видео:
Пререквизит
- Выполните шаги по интеграции sdk, описанные в Быстром старте.
- Заранее проинициализируйте рекламный SDK.
- Убедитесь, что используете самую актуальную версию Yandex Mobile Ads SDK, а в случае использовании медиации — наиболее свежую версию единой сборки.
Имплементация
Основные шаги по интеграции адаптивного sticky-баннера:
- Создать и настроить вью для отображенния баннерной рекламы.
- Зарегистрировать слушатель методов обратного вызова.
- Загрузить рекламу.
- Передать дополнительные настройки, если вы работаете через систему Adfox.
Особенности подключения адаптивного sticky-баннера
-
Все вызовы методов Yandex Mobile Ads SDK необходимо выполнять из главного потока.
-
Если вы получили ошибку в коллбэке
onAdFailedToLoad(), не пытайтесь загрузить новое объявление снова. Если всё же необходимо это сделать, ограничьте число повторных попыток загрузки рекламы. Это поможет избежать постоянных неудачных запросов и проблем с подключением в случае ограничений. -
Адаптивные sticky-баннеры лучше всего работают при использовании всей доступной ширины. В большинстве случаев это будет полная ширина экрана используемого устройства. Обязательно учитывайте применимые в приложении отступы (padding) и безопасные зоны (safe area) дисплея.
-
Для получения размера рекламного объявления, воспользуйтесь методом
BannerAdSize.stickySize(context, adWidth), принимающий в качестве аргументов контекст и доступную ширину рекламного контейнера. -
Объект
BannerAdSize, рассчитанный с помощью методаBannerAdSize.stickySize(context, adWidth)содержит постоянные значения ширины и высоты рекламы для одного и того же устройства. Протестировав макет своего приложения на конкретном устройстве, вы можете быть уверены, что размер объявления не изменится. -
Высота адаптивного sticky-баннера не будет превышать 15% высоты экрана и не меньше 50dp.
Добавление рекламной вью в макет приложения
Для отображения баннерной рекламы необходимо добавить BannerAdView в макет приложения. Сделать это можно программно или через XML-файл.
Пример добавления BannerAdView в макет экрана приложения:
# activity.xml
...
<com.yandex.mobile.ads.banner.BannerAdView
android:id="@+id/ad_container_view"
android:layout_width="match_parent"
android:layout_height="wrap_content"
app:layout_constraintBottom_toBottomOf="parent" />
...
Вы также можете создать объект BannerAdView программно:
val bannerAd = BannerAdView(this)
final BannerAdView bannerAd = new BannerAdView(this);
Загрузка и отображение рекламы
После создания и добавления BannerAdView на экран приложения, рекламу необходимо загрузить. Перед загрузкой адаптивного sticky-баннера необходимо рассчитать размер рекламы для каждого устройства.
Делается это автоматически через API sdk: BannerAdSize.stickySize(context, adWidth).
В качестве аргумента необходимо передать контекст и максимально допустимую ширину рекламного контейнера. рекомендуется использовать всю ширину экрана устройства или ширину родительского контейнера. Обязательно учитывайте применимые в приложении отступы (padding) и безопасные зоны (safe area) дисплея:
private val adSize: BannerAdSize
get() {
// Calculate the width of the ad, taking into account the padding in the ad container.
var adWidthPixels = binding.adContainerView.width
if (adWidthPixels == 0) {
// If the ad hasn't been laid out, default to the full screen width
adWidthPixels = resources.displayMetrics.widthPixels
}
val adWidth = (adWidthPixels / resources.displayMetrics.density).roundToInt()
return BannerAdSize.stickySize(this, adWidth)
}
@NonNull
private BannerAdSize getAdSize() {
final DisplayMetrics displayMetrics = getResources().getDisplayMetrics();
// Calculate the width of the ad, taking into account the padding in the ad container.
int adWidthPixels = mBinding.adContainerView.getWidth();
if (adWidthPixels == 0) {
// If the ad hasn't been laid out, default to the full screen width
adWidthPixels = displayMetrics.widthPixels;
}
final int adWidth = Math.round(adWidthPixels / displayMetrics.density);
return BannerAdSize.stickySize(this, adWidth);
}
Для загрузки рекламы также потребуется Activity context и идентификатор рекламного места, полученный вами в ПИ (adUnitId).
Для уведомления об успешной или неудачной загрузке рекламы, а также для отслеживания событий жизненного цикла адаптивного sticky-баннера, объекту класса BannerAdView необходимо установить слушатель методов обратного вызова BannerAdEventListener.
Расширить параметры запроса за рекламой можно через AdRequest.Builder(), передав в запросе данные об интересах пользователя, контекстные данные страницы, локацию или другие дополнительные данные. Дополнительные контекстные данные на запросе могут значительно улучшить качество рекламы. Подробнее читайте в разделе Таргетирование рекламы.
В следующем примере показано как загрузить адаптивный sticky-баннер. После успешной загрузки баннер отобразится автоматически:
class StickyBannerAdActivity : AppCompatActivity(R.layout.activity_sticky_banner_ad) {
private var bannerAd: BannerAdView? = null
private lateinit var binding: ActivityStickyBannerAdBinding
private val adSize: BannerAdSize
get() {
// Calculate the width of the ad, taking into account the padding in the ad container.
var adWidthPixels = binding.adContainerView.width
if (adWidthPixels == 0) {
// If the ad hasn't been laid out, default to the full screen width
adWidthPixels = resources.displayMetrics.widthPixels
}
val adWidth = (adWidthPixels / resources.displayMetrics.density).roundToInt()
return BannerAdSize.stickySize(this, adWidth)
}
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
binding = ActivityStickyBannerAdBinding.inflate(layoutInflater)
setContentView(binding.root)
// Since we're loading the banner based on the adContainerView size,
// we need to wait until this view is laid out before we can get the width
binding.adContainerView.viewTreeObserver.addOnGlobalLayoutListener(object :
ViewTreeObserver.OnGlobalLayoutListener {
override fun onGlobalLayout() {
binding.adContainerView.viewTreeObserver.removeOnGlobalLayoutListener(this);
bannerAd = loadBannerAd(adSize)
}
})
}
private fun loadBannerAd(adSize: BannerAdSize): BannerAdView {
return binding.banner.apply {
setAdSize(adSize)
setAdUnitId("your-ad-unit-id")
setBannerAdEventListener(object : BannerAdEventListener {
override fun onAdLoaded() {
// If this callback occurs after the activity is destroyed, you
// must call destroy and return or you may get a memory leak.
// Note `isDestroyed` is a method on Activity.
if (isDestroyed) {
bannerAd?.destroy()
return
}
}
override fun onAdFailedToLoad(adRequestError: AdRequestError) {
// Ad failed to load with AdRequestError.
// Attempting to load a new ad from the onAdFailedToLoad() method is strongly discouraged.
}
override fun onAdClicked() {
// Called when a click is recorded for an ad.
}
override fun onLeftApplication() {
// Called when user is about to leave application (e.g., to go to the browser), as a result of clicking on the ad.
}
override fun onReturnedToApplication() {
// Called when user returned to application after click.
}
override fun onImpression(impressionData: ImpressionData?) {
// Called when an impression is recorded for an ad.
}
})
loadAd(
AdRequest.Builder()
// Methods in the AdRequest.Builder class can be used here to specify individual options settings.
.build()
)
}
}
}
public class StickyBannerAdActivity extends AppCompatActivity {
@Nullable
private BannerAdView mBannerAd = null;
private ActivityStickyBannerAdBinding mBinding;
public StickyBannerAdActivity() {
super(R.layout.activity_sticky_banner_ad);
}
@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
mBinding = ActivityStickyBannerAdBinding.inflate(getLayoutInflater());
setContentView(mBinding.getRoot());
// Since we're loading the banner based on the adContainerView size,
// we need to wait until this view is laid out before we can get the width
mBinding.adContainerView.getViewTreeObserver().addOnGlobalLayoutListener(
new ViewTreeObserver.OnGlobalLayoutListener() {
@Override
public void onGlobalLayout() {
mBinding.adContainerView.getViewTreeObserver().removeOnGlobalLayoutListener(this);
mBannerAd = loadBannerAd(getAdSize());
}
}
);
}
@NonNull
private BannerAdSize getAdSize() {
final DisplayMetrics displayMetrics = getResources().getDisplayMetrics();
// Calculate the width of the ad, taking into account the padding in the ad container.
int adWidthPixels = mBinding.adContainerView.getWidth();
if (adWidthPixels == 0) {
// If the ad hasn't been laid out, default to the full screen width
adWidthPixels = displayMetrics.widthPixels;
}
final int adWidth = Math.round(adWidthPixels / displayMetrics.density);
return BannerAdSize.stickySize(this, adWidth);
}
@NonNull
private BannerAdView loadBannerAd(@NonNull final BannerAdSize adSize) {
final BannerAdView bannerAd = mBinding.banner;
bannerAd.setAdSize(adSize);
bannerAd.setAdUnitId("your-ad-unit-id");
bannerAd.setBannerAdEventListener(new BannerAdEventListener() {
@Override
public void onAdLoaded() {
// If this callback occurs after the activity is destroyed, you
// must call destroy and return or you may get a memory leak.
// Note `isDestroyed` is a method on Activity.
if (isDestroyed() && mBannerAd != null) {
mBannerAd.destroy();
}
}
@Override
public void onAdFailedToLoad(@NonNull final AdRequestError adRequestError) {
// Ad failed to load with AdRequestError.
// Attempting to load a new ad from the onAdFailedToLoad() method is strongly discouraged.
}
@Override
public void onAdClicked() {
// Called when a click is recorded for an ad.
}
@Override
public void onLeftApplication() {
// Called when user is about to leave application (e.g., to go to the browser), as a result of clicking on the ad.
}
@Override
public void onReturnedToApplication() {
// Called when user returned to application after click.
}
@Override
public void onImpression(@Nullable ImpressionData impressionData) {
// Called when an impression is recorded for an ad.
}
});
final AdRequest adRequest = new AdRequest.Builder()
// Methods in the AdRequest.Builder class can be used here to specify individual options settings.
.build();
bannerAd.loadAd(adRequest);
return bannerAd;
}
}
Освобождение ресурсов
Если метод обратного вызова был вызван после окончания жизненного цикла Activity, освободите ресурсы вызовом функции destroy() для используемого объекта рекламы:
private fun loadBannerAd(adSize: BannerAdSize): BannerAdView {
return binding.banner.apply {
setBannerAdEventListener(object : BannerAdEventListener {
override fun onAdLoaded() {
// If this callback occurs after the activity is destroyed, you
// must call destroy and return or you may get a memory leak.
// Note `isDestroyed` is a method on Activity.
if (isDestroyed) {
bannerAd?.destroy()
return
}
}
...
})
...
}
}
@NonNull
private BannerAdView loadBannerAd(@NonNull final BannerAdSize adSize) {
final BannerAdView bannerAd = mBinding.banner;
bannerAd.setBannerAdEventListener(new BannerAdEventListener() {
@Override
public void onAdLoaded() {
// If this callback occurs after the activity is destroyed, you
// must call destroy and return or you may get a memory leak.
// Note `isDestroyed` is a method on Activity.
if (isDestroyed() && mBannerAd != null) {
mBannerAd.destroy();
}
}
...
});
...
return bannerAd;
}
Тестирование интеграции адаптивного sticky-баннера
Использование демоблоков для тестирования рекламы
Для проверки корректной интеграции адаптивного sticky-баннера, а также для тестирования вашего приложения, рекомендуется использовать тестовую рекламу.
Для гарантированного возврата тестовых объявлений на каждый запрос за рекламой, мы создали специальный демонстрационный идентификатор рекламного места. Используйте его для проверки корректной интеграции рекламы.
Демонстрационный adUnitId: demo-banner-yandex.
Важно
Убедитесь, что перед выкладыванием приложения в store, вы заменили демонстрационный идентификатор рекламного места на настоящий, полученный в ПИ.
Список всех доступных демонстрационных идентификаторов рекламного места доступен в разделе Демоблоки для тестирования.
Проверка корректной интеграции рекламы
Проверить корректность интеграции адаптивного sticky-баннера можно через встроенный в sdk анализатор.
Данный инструмент проверяет корректность подключения рекламы и выводит в лог подробный отчет. Для просмотра отчета, выполните поиск по ключевому слову "YandexAds" в инструменте отладки Android-приложений Logcat.
adb logcat -v brief '*:S YandexAds'
В случае успешной интеграции, вы увидите следующее сообщение:
adb logcat -v brief '*:S YandexAds'
mobileads$ adb logcat -v brief '*:S YandexAds'
I/YandexAds(13719): [Integration] Ad type banner was integrated successfully
В случае обнаружения проблем при интеграции баннерной рекламы — подробный отчет о проблемах и рекомендации по их устранению.
Дополнительные ресурсы
-
Ссылка на github.