Как настроить расширенные встроенные функции

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

Требования

• Интегрируйте формат нативных объявлений.

Настройки объектов

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

Настройки соотношения сторон

Настройки соотношения сторон медиаконтента позволяют задать предпочтительное соотношение сторон креативов.

Вызовите функцию NativeAdRequest.Builder.setMediaAspectRatio() со значением NativeAd.NativeMediaAspectRatio.

• Если значение не задано, возвращаемое объявление может иметь любое соотношение сторон.

• Если задать это значение, вы сможете улучшить качество показа, указав предпочтительное соотношение сторон.

В приведенном ниже примере SDK получает указание отдавать предпочтение изображению или видео с определенным соотношением сторон.

val adRequest = NativeAdRequest.Builder(
  "/21775744923/example/native",
  listOf(NativeAd.NativeAdType.NATIVE))
  .setMediaAspectRatio(NativeAd.NATIVE_MEDIA_ASPECT_RATIO_LANDSCAPE)
  .build()

NativeAdRequest adRequest = new NativeAdRequest.Builder(
  "/21775744923/example/native",
  List.of(NativeAd.NativeAdType.NATIVE))
  .setMediaAspectRatio(NativeAd.NATIVE_MEDIA_ASPECT_RATIO_LANDSCAPE)
  .build();

Управление скачиванием изображений

Управление скачиванием изображений позволяет вам выбирать, какие объекты изображений или только URI будут возвращаться SDK.

Позвони по номеру NativeAdRequest.Builder.disableImageDownloading().

• По умолчанию элементы управления скачиванием изображений отключены.

• Если эта функция отключена, GMA Next-Gen SDK автоматически добавит изображение и URI.

• Если эта функция включена, SDK заполняет только URI, а вы можете скачивать изображения по своему усмотрению.

В следующем примере показано, как настроить SDK на возврат только URI.

val adRequest = NativeAdRequest.Builder(
    "/21775744923/example/native",
    listOf(NativeAd.NativeAdType.NATIVE))
    .setMediaAspectRatio(NativeAd.NATIVE_MEDIA_ASPECT_RATIO_LANDSCAPE)
    .disableImageDownloading()
    .build()

val adCallback: NativeAdLoaderCallback =
  object : NativeAdLoaderCallback {
    override fun onNativeAdLoaded(nativeAd: NativeAd) {
      // Get the image uri.
      val imageUri = nativeAd.image?.uri
    }
  };

// Load the native ad with the ad request and callback.
NativeAdLoader.load(adRequest, adLoaderCallback);

NativeAdRequest adRequest = new NativeAdRequest.Builder(
  "/21775744923/example/native",
  List.of(NativeAd.NativeAdType.NATIVE))
  .disableImageDownloading()
  .build();

NativeAdLoaderCallback adLoaderCallback =
  new NativeAdLoaderCallback() {
    @Override
    public void onNativeAdLoaded(@NonNull NativeAd nativeAd) {
      // Get the image uri.
      Uri imageUri = nativeAd.getImage().getUri();
    }
  };

// Load the native ad with the ad request and callback.
NativeAdLoader.load(adRequest, adLoaderCallback);

Настройки данных изображений

В некоторых объявлениях показывается не одно, а несколько изображений. Используйте эту функцию, чтобы указать, готово ли ваше приложение показывать все изображения или только одно.

• Настройки данных изображений по умолчанию отключены.

• Если эта функция отключена, приложение будет отправлять в SDK запрос на предоставление только первого изображения из серии.

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

В приведенном ниже примере SDK получает инструкции вернуть несколько объектов изображений.

Места размещения значка "Выбор рекламы"

В этом разделе рассказывается, как разместить оверлей AdChoices. Вы можете разместить его в одном из четырех углов экрана или в специальном представлении.

Настройки положения значка "Выбор рекламы"

Позиция AdChoices позволяет выбрать угол, в котором будет показываться значок "Выбор рекламы".

Вызовите функцию NativeAdRequest.Builder.setAdChoicesPlacement() со значением NativeAdRequest.AdChoicesPlacement.

• Если значение не задано, значок "Выбор рекламы" будет размещен в правом верхнем углу.

• Если задано, значок "Выбор рекламы" размещается в указанном месте.

В следующем примере показано, как задать собственное положение значка AdChoices.

val adRequest = NativeAdRequest.Builder(
  "/21775744923/example/native",
  listOf(NativeAd.NativeAdType.NATIVE))
  .setAdChoicesPlacement(NativeAdOptions.ADCHOICES_BOTTOM_RIGHT)
  .build()

NativeAdRequest adRequest = new NativeAdRequest.Builder(
  "/21775744923/example/native",
  List.of(NativeAd.NativeAdType.NATIVE))
  .setAdChoicesPlacement(NativeAdOptions.ADCHOICES_BOTTOM_RIGHT)
  .build();

Специальный режим просмотра AdChoices

Функция "Специальное представление значка "Выбор рекламы" позволяет размещать значок "Выбор рекламы" в любом месте. Это отличается от настроек положения значка "Выбор рекламы", которые позволяют указать только один из четырех углов.

Вызовите функцию NativeAdView.setAdChoicesView() со значением AdChoicesView.

В приведенном ниже примере показано, как задать специальный вид значка "Выбор рекламы", который будет отрисовываться внутри элемента AdChoicesView.

override fun onNativeAdLoaded(nativeAd: NativeAd) {
  val nativeAdView = NativeAdView(applicationContext)
  val adChoicesView = AdChoicesView(this)
  nativeAdView.adChoicesView = adChoicesView
}

public void onNativeAdLoaded(@NonNull NativeAd nativeAd) {
  NativeAdView nativeAdView = new NativeAdView(getApplicationContext());
  AdChoicesView adChoicesView = new AdChoicesView(this);
  nativeAdView.setAdChoicesView(adChoicesView);
}

Управление воспроизведением

В этом разделе рассказывается, как настроить воспроизведение видеообъявлений. Вы можете задать начальное состояние отключения звука и реализовать собственные элементы управления воспроизведением.

Поведение при запуске без звука

Поведение "Начать с отключенным звуком" позволяет отключить или включить звук в начале видео.

Вызовите функцию VideoOptions.Builder.setStartMuted() со значением boolean и функцию NativeAdOptions.Builder.setVideoOptions().

• По умолчанию звук при запуске видео отключен.

• Если параметр отключен, приложение запрашивает, чтобы видео начиналось со звуком.

• Если этот параметр включен, приложение запрашивает, чтобы видео начиналось с отключенным звуком.

В примере ниже показано, как запустить видео с включенным звуком.

val videoOptions = VideoOptions.Builder()
  .setStartMuted(false)
  .build()

val adRequest = NativeAdRequest.Builder(
  "/21775744923/example/native",
  listOf(NativeAd.NativeAdType.NATIVE))
  .setVideoOptions(videoOptions)
  .build()

VideoOptions videoOptions = VideoOptions.Builder()
  .setStartMuted(false)
  .build()

NativeAdRequest adRequest = new NativeAdRequest.Builder(
  "/21775744923/example/native",
  List.of(NativeAd.NativeAdType.NATIVE))
  .setVideoOptions(videoOptions)
  .build()

Персонализированные элементы управления воспроизведением

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

Чтобы задать начальное состояние звука в объявлениях, вызовите функцию VideoOptions.Builder.setCustomControlsRequested().

• По умолчанию персонализированные элементы управления в видео отключены.

• Если параметр отключен, в видео будут показываться элементы управления, отрисованные SDK.

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

VideoOptions.Builder.setCustomControlsRequested().

В следующем примере показано, как запросить видео с пользовательскими элементами управления воспроизведением.

val videoOptions: VideoOptions.Builder()
  .setCustomControlsRequested(true)
  .build()

val adRequest = new NativeAdRequest.Builder(
  "/21775744923/example/native",
  listOf(NativeAd.NativeAdType.NATIVE))
  .setVideoOptions(videoOptions)
  .build()

VideoOptions VideoOptions = VideoOptions.Builder()
  .setCustomControlsRequested(true)
  .build()

NativeAdRequest adRequest = new NativeAdRequest.Builder(
  "/21775744923/example/native",
  List.of(NativeAd.NativeAdType.NATIVE))
  .setVideoOptions(videoOptions)
  .build()

Как проверить, включены ли специальные элементы управления

Поскольку во время запроса неизвестно, будет ли в объявлении, которое вернет сервер, разрешено использовать специальные элементы управления видео, необходимо проверить, включены ли они.

  val adCallback: NativeAdLoaderCallback =
    object : NativeAdLoaderCallback {
      override fun onNativeAdLoaded(nativeAd: NativeAd) {
        val mediaContent = nativeAd.mediaContent;
        if (mediaContent != null) {
          val videoController = mediaContent.videoController;
          val canShowCustomControls = videoController?.isCustomControlsEnabled();
        }
      }
    };

NativeAdLoaderCallback adCallback =
  new NativeAdLoaderCallback() {
    @Override
    public void onNativeAdLoaded(@NonNull NativeAd nativeAd) {
      MediaContent mediaContent = nativeAd.getMediaContent();
      if (mediaContent != null) {
        VideoController videoController = mediaContent.getVideoController();
        if (videoController != null) {
          boolean canShowCustomControls = videoController.isCustomControlsEnabled();
        }
      }
    }
  };

Как добавить собственные элементы управления видео

При создании собственных элементов управления видео следуйте приведенным ниже рекомендациям.

1. Представление специальных элементов управления должно быть дочерним по отношению к представлению нативного объявления. При таком подходе при расчете видимости с помощью Open Measurement пользовательские элементы управления будут считаться допустимым препятствием.
2. Не создавайте невидимый оверлей поверх всего медиаконтента. Оверлеи блокируют клики по медиаконтенту, что негативно влияет на эффективность нативных объявлений. Вместо этого создайте небольшой оверлей, который будет достаточно большим, чтобы вместить элементы управления.

Специальные жесты

Специальные жесты для кликов – это функция нативных объявлений, которая позволяет регистрировать свайпы по объявлениям как клики. Она работает в приложениях, где для навигации по контенту используются жесты прокрутки. В этом руководстве рассказывается, как включить в нативных объявлениях специальные жесты для кликов.

Вызовите NativeAdRequest.Builder.enableCustomClickGestureDirection() с NativeAd.SwipeGestureDirection и значением boolean.

• По умолчанию специальные жесты отключены.

• Если она отключена, приложение поддерживает обычное поведение при клике.

• Если эта функция включена, в приложении поддерживаются специальные жесты.

В примере ниже реализован специальный жест пролистывания вправо, при этом сохраняется обычное поведение при нажатии.

val adRequest =
  NativeAdRequest.Builder(AD_UNIT_ID, listOf(NativeAdType.NATIVE))
    .enableCustomClickGestureDirection(
      SwipeGestureDirection.RIGHT,
      /* customClickGestureAllowTaps= */ true,
    )
    .build()

NativeAdRequest adRequest =
    new NativeAdRequest.Builder(AD_UNIT_ID, List.of(NativeAdType.NATIVE))
        .enableCustomClickGestureDirection(
            SwipeGestureDirection.RIGHT, /* customClickGestureAllowTaps= */ true)
        .build();

Как отслеживать события жестов пролистывания

Чтобы отслеживать события жестов пролистывания, вызовите метод NativeAd.setAdEventCallback() с параметром NativeAdEventCallback и реализуйте метод onAdSwipeGestureClicked().

  val adCallback: NativeAdLoaderCallback =
    object : NativeAdLoaderCallback {
      override fun onNativeAdLoaded(nativeAd: NativeAd) {
        // Implement the onAdSwipeGestureClicked() method.
        val nativeAdCallback: NativeAdEventCallback = object : NativeAdEventCallback {
          override fun onAdSwipeGestureClicked() {
            // A swipe gesture click has occurred.
          }
        }
      }
    }
  // Load the native ad with the ad request and callback.
  NativeAdLoader.load(adRequest, adCallback)

  NativeAdLoaderCallback adCallback =
    new NativeAdLoaderCallback() {
      @Override
      public void onNativeAdLoaded(@NonNull NativeAd nativeAd) {
        // Implement the onAdSwipeGestureClicked() method.
        NativeAdEventCallback nativeAdCallback = new NativeAdEventCallback() {
          @Override
          public void onAdSwipeGestureClicked() {
            // A swipe gesture click has occurred.
          }
        };
      }
    };
  // Load the native ad with the ad request and callback.
  NativeAdLoader.load(adRequest, adCallback);

Медиация

Специальные жесты для кликов работают только с нативными объявлениями, которые отрисовывает Google Mobile Ads SDK. Источники объявлений, для визуализации которых требуются сторонние SDK, не реагируют на настройки специальных инструкций по кликам.