Адаптивный inline-баннер

Адаптивный inline-баннер — гибкий формат баннерной рекламы, обеспечивающий максимальную эффективность за счет оптимизации размера рекламы для каждого устройства.

Данный тип рекламы позволяет разработчикам указывать максимально допустимые ширину и высоту объявления, при этом оптимальный размер рекламы определяется автоматически. Чтобы выбрать лучший размер объявления, встроенные адаптивные баннеры используют максимальную, а не фиксированную высоту. Это позволяет повысить производительность.

Как правило, такой формат используется в приложениях-лентах или там, где допустимо обеспечить основной фокус на рекламе.

Внешний вид

Это руководство покажет, как интегрировать адаптивный inline-баннер в приложение на Compose Multiplatform. В дополнение к примерам кода и инструкции, оно также содержит рекомендации по использованию данного формата рекламы, а также ссылки на дополнительные ресурсы.

Пререквизит

  1. Выполните шаги по интеграции Yandex Mobile Ads Compose Multiplatform Plugin, описанные в Быстром старте.
  2. Убедитесь, что используете самую актуальную версию Yandex Mobile Ads Compose Multiplatform Plugin, а в случае использовании медиации — наиболее свежую версию единой сборки.

Имплементация

Основные шаги по интеграции адаптивного inline-баннера:

  • Добавить в интерфейс composable Banner и передать BannerAdSize.Inline с шириной контейнера и максимальной высотой.
  • Задать коллбэки жизненного цикла объявления через BannerEvents.

Особенности подключения адаптивного inline-баннера

  1. Если коллбэк onAdFailedToLoad сообщает об ошибке, не пытайтесь сразу загрузить новое объявление. Если без повторной загрузки не обойтись, ограничьте число попыток — так вы снизите риск постоянных неудачных запросов и проблем с подключением при ограничениях на стороне сети.

  2. Чтобы адаптивные inline-баннеры работали корректно, сделайте макеты приложения адаптивными. Иначе объявления могут отображаться некорректно.

  3. Адаптивные inline-баннеры лучше всего работают на полной доступной ширине. Чаще всего это ширина экрана устройства. Учитывайте отступы в приложении и безопасную зону экрана.

  4. Адаптивный inline-баннер рассчитан на размещение в прокручиваемом контенте. Высота может быть сопоставима с высотой экрана или ограничена максимумом, в зависимости от API.

  5. Размер баннера задавайте через BannerAdSize.Inline(width, maxHeight) — доступная ширина контейнера и максимально допустимая высота объявления.

  6. Значение BannerAdSize, собранное через BannerAdSize.Inline(width, maxHeight), несёт технические данные для подбора размеров на бэкенде. Фактическая высота после отрисовки может меняться от загрузки к загрузке. Если продукту нужна подгонка в пикселях, измеряйте контейнер после показа креатива.

Добавление баннера в макет

Разместите композабл Banner там, где должен быть inline-баннер (например, внутри прокручиваемой колонки ленты).

Пример размещения на экране:

@Composable
fun BannerSlot(adRequest: AdRequest, containerWidth: Int, maxHeight: Int) {
    Banner(
        adRequest = adRequest,
        adSize = BannerAdSize.Inline(width = containerWidth, maxHeight = maxHeight),
        modifier = Modifier.fillMaxWidth(),
        events = BannerEvents(
            onAdLoaded = { /* ad loaded */ },
            onAdFailedToLoad = { error -> /* handle error */ },
            onAdClicked = { /* ad clicked */ },
            onImpression = { data -> /* impression tracked */ },
        ),
    )
}

Загрузка и отображение рекламы

Композабл Banner сам загружает и обновляет объявление для переданного AdRequest, когда попадает в композицию.

Передайте в BannerAdSize.Inline ширину рекламного контейнера и максимально допустимую высоту. Рекомендуем полную ширину родителя или экрана с учётом отступов и safe area. Ширину можно взять из BoxWithConstraints или собственных измерений макета:

BoxWithConstraints(modifier = Modifier.fillMaxWidth()) {
    val widthDp = maxWidth.value.toInt()
    Banner(
        adRequest = adRequest,
        adSize = BannerAdSize.Inline(width = widthDp, maxHeight = bannerMaxHeightDp),
        modifier = Modifier.fillMaxWidth(),
        events = BannerEvents(/* ... */),
    )
}

Для загрузки нужен идентификатор рекламного места из интерфейса Рекламной сети Яндекса (adUnitId).

Чтобы получать уведомления об успешной или неуспешной загрузке и отслеживать жизненный цикл inline-баннера, используйте BannerEvents, как в примере выше.

Параметры запроса расширяйте через AdRequest (например targeting, parameters, preferredTheme). Дополнительный контекст в запросе заметно улучшает качество подбора рекламы. Подробнее — в разделе Таргетирование рекламы.

Ниже — пример загрузки адаптивного inline-баннера: после успешной загрузки баннер показывается автоматически.

@Composable
fun InlineBanner(adUnitId: String) {
    Banner(
        adRequest = AdRequest(adUnitId = adUnitId),
        adSize = BannerAdSize.Inline(width = 320, maxHeight = 50),
        modifier = Modifier.fillMaxWidth(),
        events = BannerEvents(
            onAdLoaded = {
                // The ad was loaded successfully and will be shown.
            },
            onAdFailedToLoad = { error ->
                // Ad failed to load with AdRequestError.
                // Attempting to load a new ad from the onAdFailedToLoad() method is strongly discouraged.
            },
            onAdClicked = {
                // Called when a click is recorded for an ad.
            },
            onImpression = { impressionData ->
                // Called when an impression is recorded for an ad.
            },
        ),
    )
}

На этапе интеграции в качестве adUnitId можно использовать 'demo-banner-yandex'; перед релизом замените на боевой идентификатор.

Освобождение ресурсов

Когда пользователь уходит с экрана, уберите Banner из композиции (или перестаньте его отрисовывать) — так освободится нативное представление. Не храните скрытый баннер только ради повторного использования: при следующем показе слота создайте новый Banner с новым AdRequest.

Тестирование интеграции адаптивного inline-баннера

Использование демоблоков для тестирования рекламы

Для проверки корректной интеграции адаптивного inline-баннера и тестирования приложения используйте тестовую рекламу. Для гарантированного возврата тестовых объявлений на каждый запрос за рекламой вы можете использовать специальный демонстрационный идентификатор рекламного места.

Демонстрационный adUnitId: demo-banner-yandex.

Важно

Убедитесь, что перед выкладыванием приложения в магазин вы заменили демонстрационный идентификатор рекламного места на настоящий, полученный в интерфейсе Рекламной сети Яндекса.

Список всех доступных демонстрационных идентификаторов рекламного места доступен в разделе Демоблоки для тестирования.

Проверка корректной интеграции рекламы

Проверить корректность интеграции адаптивного inline-баннера можно через встроенный в 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

В случае обнаружения проблем при интеграции баннерной рекламы вы получите подробный отчет о проблемах и рекомендации по их устранению.

Использование демоблоков для тестирования рекламы

Для проверки корректной интеграции рекламы и тестирования приложения используйте тестовую рекламу. Для гарантированного возврата тестовых объявлений на каждый запрос за рекламой вы можете использовать специальный демонстрационный идентификатор рекламного места.

Демонстрационный adUnitId: demo-banner-yandex.

Важно

Убедитесь, что перед выкладыванием приложения в магазин вы заменили демонстрационный идентификатор рекламного места на настоящий, полученный в интерфейсе Рекламной сети Яндекса.

Список всех доступных демонстрационных идентификаторов рекламного места доступен в разделе Демоблоки для тестирования.

Проверка корректной интеграции рекламы

Проверить корректность интеграции рекламы можно через нативный инструмент Console.

Чтобы получить возможность просматривать расширенные логи, необходимо вызвать метод enableLogging класса YandexAds.

YandexAds.enableLogging()

Для просмотра логов SDK в инструменте Console установите Subsystem = com.mobile.ads.ads.sdk. Вы можете фильтровать логи по категории и уровню ошибки.

В случае обнаружения проблем при интеграции рекламы вы увидите подробный отчет о проблемах и рекомендации по их устранению.

Дополнительные ресурсы

Предыдущая
Форматы рекламы
Следующая
Адаптивный sticky-баннер