Как использовать специальные форматы нативных объявлений

Выберите платформу: Android iOS Android (устаревшая версия)

Помимо стандартных форматов нативных объявлений, издатели Менеджера рекламы могут создавать собственные форматы, определяя специальные списки объектов. Они называются специальными форматами нативных объявлений и могут использоваться с объявлениями с резервированием. Это позволяет издателям передавать в свои приложения произвольные структурированные данные. Такие объявления представлены объектом NativeCustomFormatAd.

Примечание. Класс NativeCustomFormatAd не поддерживает получение объекта ResponseInfo или пакета extras.

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

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

Как загрузить специальное нативное объявление

Как и нативные объявления, специальные форматы нативных объявлений загружаются с помощью класса AdLoader:

Java

AdLoader adLoader = new AdLoader.Builder(this, "/21775744923/example/native")
    .forCustomFormatAd("12387226",
        new NativeCustomFormatAd.OnCustomFormatAdLoadedListener() {
          @Override
          public void onCustomFormatAdLoaded(NativeCustomFormatAd ad) {
            // Show the custom format and record an impression.
          }
        },
        new NativeCustomFormatAd.OnCustomClickListener() {
          @Override
          public void onCustomClick(NativeCustomFormatAd ad, String s) {
            // Handle the click action
          }
        })
    .forCustomFormatAd("12406343",
        new NativeCustomFormatAd.OnCustomFormatAdLoadedListener() {
          @Override
          public void onCustomFormatAdLoaded(NativeCustomFormatAd ad) {
            // Show the custom format and record an impression.
          }
        },
        new NativeCustomFormatAd.OnCustomClickListener() {
          @Override
          public void onCustomClick(NativeCustomFormatAd ad, String s) {
            // Handle the click action
          }
        })
    .build();

Kotlin

val adLoader = AdLoader.Builder(this, "/21775744923/example/native")
  .forCustomFormatAd(
    "12387226",
    { customFormatAd ->
      // Show the custom format and record an impression.
    },
    { customFormatAd, s ->
      // Handle the click action
    })
  .forCustomFormatAd(
    "12406343",
    { customFormatAd ->
      // Show the custom format and record an impression.
    },
    { customFormatAd, s ->
      // Handle the click action
    })
  .build()

Метод forCustomFormatAd настраивает AdLoader для запроса специальных форматов нативных объявлений. Этот метод можно вызывать несколько раз для разных идентификаторов специальных форматов. Метод принимает следующие параметры:

• Идентификатор специального формата нативного объявления, который должен запрашивать AdLoader. Каждому формату нативного объявления, созданному пользователем, присваивается идентификатор. Этот параметр указывает, какой формат объявления должен запрашивать AdLoader.
• OnCustomFormatAdLoadedListener, который вызывается, когда объявление загружено.
• Необязательный параметр OnCustomClickListener, который вызывается, когда пользователь нажимает на объявление. Подробнее об этом прослушивателе читайте в разделе "Обработка кликов и показов".

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

Примечание. Если рекламный блок настроен для показа объявлений нескольких форматов, то forNativeAd и forCustomFormatAd можно использовать одновременно с одним AdLoader.

Идентификатор специального формата нативного объявления

Идентификатор формата, который используется для определения специального формата нативного объявления, можно найти в интерфейсе Менеджера рекламы в разделе Нативные в раскрывающемся меню Выполнение.

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

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

Специальные форматы нативных объявлений в КМС

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

1. Текстовые и графические объекты доступны через методы получения getText() и getImage(), которые принимают название поля в качестве параметра.
2. Поскольку в Google нет специального класса ViewGroup, который можно зарегистрировать, вам нужно регистрировать показы и клики вручную.
3. Если в специальном нативном объявлении нет видеообъекта, то медиаконтент имеет тип null.

Вот пример функции, которая показывает NativeCustomFormatAd:

Java

public void displayCustomFormatAd (ViewGroup parent,
                                     NativeCustomFormatAd customFormatAd) {
    // Inflate a layout and add it to the parent ViewGroup.
    LayoutInflater inflater = (LayoutInflater) parent.getContext()
            .getSystemService(Context.LAYOUT_INFLATER_SERVICE);
    View adView = inflater.inflate(R.layout.custom_format_ad, parent);

    // Locate the TextView that will hold the value for "Headline" and
    // set its text.
    TextView myHeadlineView = (TextView) adView.findViewById(R.id.headline);
    myHeadlineView.setText(customFormatAd.getText("Headline"));

    // Locate the ImageView that will hold the value for "MainImage" and
    // set its drawable.
    Button myMainImageView = (ImageView) adView.findViewById(R.id.main_image);
    myMainImageView.setImageDrawable(
            customFormatAd.getImage("MainImage").getDrawable());

    ...
    // Continue locating views and displaying assets until finished.
    ...
}

Kotlin

public fun displayCustomFormatAd (parent: ViewGroup,
                                customFormatAd: NativeCustomFormatAd) {
    val adView = layoutInflater
            .inflate(R.layout.ad_simple_custom_format, null)

    val myHeadlineView = adView.findViewById<TextView>(R.id.headline)
    myHeadlineView.setText(customFormatAd.getText("Headline"));

    // Locate the ImageView that will hold the value for "MainImage" and
    // set its drawable.
    val myMainImageView = adView.findViewById(R.id.main_image);
    myMainImageView.setImageDrawable(
            customFormatAd.getImage("MainImage").drawable);

    ...
    // Continue locating views and displaying assets until finished.
    ...
}

Нативные видеообъявления специальных форматов

При создании специального формата вы можете сделать его совместимым с видео.

В реализации приложения вы можете использовать NativeCustomFormatAd.getMediaContent(), чтобы получить медиаконтент. Затем вызовите setMediaContent(), чтобы задать медиаконтент в представлении. Если в объявлении есть медиаконтент null, найдите альтернативный способ показать объявление без видео.

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

Java

// Called when a custom native ad loads.
@Override
public void onCustomFormatAdLoaded(final NativeCustomFormatAd ad) {

  MediaContent mediaContent = ad.getMediaContent();

  // Assumes you have a FrameLayout in your view hierarchy with the ID media_placeholder.
  FrameLayout mediaPlaceholder = (FrameLayout) findViewById(R.id.media_placeholder);

  // Apps can check the MediaContent's hasVideoContent property to determine if the
  // NativeCustomFormatAd has a video asset.
  if (mediaContent != null && mediaContent.hasVideoContent()) {
    MediaView mediaView = new MediaView(mediaPlaceholder.getContext());
    mediaView.setMediaContent(mediaContent);
    mediaPlaceholder.addView(mediaView);

    // Create a new VideoLifecycleCallbacks object and pass it to the VideoController. The
    // VideoController will call methods on this object when events occur in the video
    // lifecycle.
    VideoController vc = mediaContent.getVideoController();
    vc.setVideoLifecycleCallbacks(
        new VideoController.VideoLifecycleCallbacks() {
          @Override
          public void onVideoEnd() {
            // Publishers should allow native ads to complete video playback before
            // refreshing or replacing them with another ad in the same UI location.
            super.onVideoEnd();
          }
        });
  } else {
    ImageView mainImage = new ImageView(this);
    mainImage.setAdjustViewBounds(true);
    mainImage.setImageDrawable(ad.getImage("MainImage").getDrawable());
    mediaPlaceholder.addView(mainImage);
    mainImage.setOnClickListener(
        new View.OnClickListener() {
          @Override
          public void onClick(View view) {
            ad.performClick("MainImage");
          }
        });
  }
}

Kotlin

// Called when a custom native ad loads.
NativeCustomFormatAd.OnCustomFormatAdLoadedListener { ad ->

  val mediaContent = ad.mediaContent

  // Apps can check the MediaContent's hasVideoContent property to determine if the
  // NativeCustomFormatAd has a video asset.
  if (mediaContent != null && mediaContent.hasVideoContent()) {
    val mediaView = MediaView(mediaPlaceholder.getContest())
    mediaView.mediaContent = mediaContent

    val videoController = mediaContent.videoController

    // Create a new VideoLifecycleCallbacks object and pass it to the VideoController. The
    // VideoController will call methods on this object when events occur in the video
    // lifecycle.
    if (videoController != null) {
      videoController.videoLifecycleCallbacks =
        object : VideoController.VideoLifecycleCallbacks() {
          override fun onVideoEnd() {
            // Publishers should allow native ads to complete video playback before refreshing
            // or replacing them with another ad in the same UI location.
            super.onVideoEnd()
          }
        }
    }
  } else {
    val mainImage = ImageView(this)
    mainImage.adjustViewBounds = true
    mainImage.setImageDrawable(ad.getImage("MainImage")?.drawable)

    mainImage.setOnClickListener { ad.performClick("MainImage") }
    customTemplateBinding.simplecustomMediaPlaceholder.addView(mainImage)
  }
}

Чтобы посмотреть, как работает нативное видеообъявление, скачайте пример специальной обработки в Менеджере рекламы.

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

Как показывать значок "Выбор рекламы"

В рамках поддержки закона ЕС "О цифровых услугах" (DSA) объявления с резервированием, которые показываются в Европейской экономической зоне (ЕЭЗ), должны содержать значок "Выбор рекламы" и ссылку на страницу Google "Об этой рекламе". В нативных объявлениях должен показываться значок "Выбор рекламы". Ответственность за это несете вы. Настоятельно рекомендуем вам отображать значок "Выбор рекламы" и устанавливать для него прослушиватель кликов при отрисовке основных объектов объявлений.

В примере ниже предполагается, что вы определили элемент <ImageView /> в иерархии View, чтобы разместить логотип "Выбор рекламы".

Важно! Размер значка "Выбор рекламы" должен быть не менее 15 x 15 пикселей.

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android">
    <ImageView
        android:id="@+id/adChoices"
        android:layout_width="15dp"
        android:layout_height="15dp"
        android:adjustViewBounds="true"
        android:contentDescription="AdChoices icon." />
</LinearLayout>

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

Java

private AdSimpleCustomTemplateBinding customTemplateBinding;

private void populateAdView(final NativeCustomFormatAd nativeCustomFormatAd) {
  // Render the AdChoices icon.
  String adChoicesKey = NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW;
  NativeAd.Image adChoicesAsset = nativeCustomFormatAd.getImage(adChoicesKey);
  if (adChoicesAsset == null) {
    customTemplateBinding.adChoices.setVisibility(View.GONE);
  } else {
    customTemplateBinding.adChoices.setVisibility(View.VISIBLE);
    customTemplateBinding.adChoices.setImageDrawable(adChoicesAsset.getDrawable());

    // Enable clicks on AdChoices.
    customTemplateBinding.adChoices.setOnClickListener(
        new View.OnClickListener() {
          @Override
          public void onClick(View v) {
            nativeCustomFormatAd.performClick(adChoicesKey);
          }
        });
  }
  ...
}

Kotlin

private lateinit var customTemplateBinding: AdSimpleCustomTemplateBinding

private fun populateAdView(nativeCustomFormatAd: NativeCustomFormatAd) {
  // Render the AdChoices icon.
  val adChoicesKey = NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW
  val adChoicesAsset = nativeCustomFormatAd.getImage(adChoicesKey)
  if (adChoicesAsset == null) {
    customTemplateBinding.adChoices.visibility = View.GONE
  } else {
    customTemplateBinding.adChoices.setImageDrawable(adChoicesAsset.drawable)
    customTemplateBinding.adChoices.visibility = View.VISIBLE

    // Enable clicks on AdChoices.
    customTemplateBinding.adChoices.setOnClickListener {
      nativeCustomFormatAd.performClick(adChoicesKey)
    }
  }
  ...
}

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

Регистрация показов и кликов

Ваше приложение должно регистрировать показы и сообщать о кликах в Google Mobile Ads SDK (Legacy).

Регистрация показов

Чтобы зарегистрировать показ нативного объявления, вызовите метод recordImpression():

myCustomFormatAd.recordImpression();

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

Клики по ссылке для жалобы

Чтобы сообщить SDK о клике по объекту, вызовите метод performClick() объявления. Укажите название объекта, по которому был выполнен клик, используя ту же строку, которую вы задали в интерфейсе Менеджера рекламы.

myCustomFormatAd.performClick("MainImage");

Обратите внимание, что этот метод не нужно вызывать для каждого представления, связанного с объявлением. Если у вас есть другое поле, например "Подпись", которое должно показываться, но не должно быть доступно для нажатия, то для этого объекта вызывать метод performClick не нужно.

Как реагировать на специальные действия по клику

Когда пользователь нажимает на объявление специального формата, SDK может выполнить одно из трех действий (в указанном порядке):

1. Вызовите OnCustomClickListener, если он был предоставлен.
2. Для каждого URL ссылки на контент в объявлении попытайтесь найти распознаватель контента и запустите первый из них, который будет распознан.
3. Откройте браузер и перейдите по целевому URL объявления.

Чтобы реализовать собственное действие по клику, укажите OnCustomClickListener:

Java

AdLoader adLoader = new AdLoader.Builder(context, "/21775744923/example/native")
    .forCustomFormatAd("10063170",
      new NativeCustomFormatAd.OnCustomFormatAdLoadedListener() {
        // Display the ad.
      },
      new NativeCustomFormatAd.OnCustomClickListener() {
          @Override
          public void onCustomClick(NativeCustomFormatAd ad, String assetName) {
            Log.i("MyApp", "A custom click just happened for " + assetName + "!");
          }
      }).build();

Kotlin

val adLoader = AdLoader.Builder(this, "/21775744923/example/native")
    .forCustomFormatAd("10063170",
        { ad ->
            // Display the ad.
        },
        { ad, assetName ->
                Log.i("MyApp", "A custom click just happened for $assetName!")
    }).build()

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

Такой поток информации полезен по нескольким причинам, но самое главное – он позволяет SDK контролировать ответ на клик. Например, он может автоматически отправлять запросы на внешние URL отслеживания, заданные для креатива, и выполнять другие задачи в фоновом режиме без дополнительного кода.