Пользовательские форматы нативной рекламы

Пользовательские форматы нативной рекламы

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

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

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

Создайте AdLoader

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

Ява

AdLoader adLoader = new AdLoader.Builder(context, "/21775744923/example/native")
    .forCustomFormatAd("10063170",
      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
          }
      })
    .withAdListener( ... )
    .withNativeAdOptions( ... )
    .build();

Котлин

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

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

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

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

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

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

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

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

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

Отображать собственные форматы нативных объявлений

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

1. Поскольку класс NativeCustomFormatAd предназначен для обработки любых пользовательских форматов нативных объявлений, которые вы определяете в Менеджере рекламы, он не имеет имен «геттеров» для активов. Вместо этого он предлагает такие методы, как getText и getImage , которые принимают имя поля в качестве параметра.
2. Не существует специального класса просмотра рекламы, такого как NativeAdView который можно было бы использовать с NativeCustomFormatAd . Вы можете использовать любой макет, который имеет смысл для вашего пользовательского опыта.
3. Поскольку специального класса ViewGroup не существует, вам не нужно регистрировать какие-либо представления, которые вы используете для отображения ресурсов объявления. Это экономит несколько строк кода при показе объявления, но также означает, что вам придется проделать небольшую дополнительную работу для обработки кликов в дальнейшем.

Вот пример функции, которая отображает NativeCustomFormatAd :

Ява

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.
    ...
}

Котлин

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.
    ...
}

Отображение значка «Выбор рекламы»

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

В следующем примере предполагается, что вы определили элемент <ImageView /> в иерархии представлений для хранения логотипа AdChoices.

Важно! Установите значок «Выбор рекламы» размером не менее 15 на 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>

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

Ява

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);
          }
        });
  }
  ...
}

Котлин

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-адресов изображений, ресурс AdChoices учитывает этот параметр и возвращает только URL-адрес изображения.

Нативное видео для пользовательских форматов нативной рекламы

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

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

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

В приведенном ниже примере проверяется наличие в объявлении видеоконтента и отображается изображение вместо него, если видео недоступно:

Ява

// 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");
          }
        });
  }
}

Котлин

// 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)
  }
}

См. MediaContent для получения дополнительной информации о том, как настроить видеоизображение нативной рекламы.

Загрузите пример пользовательского рендеринга Менеджера рекламы, чтобы увидеть рабочий пример нативного видео в действии.

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

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

Записывайте впечатления

Чтобы записать показ объявления специального формата, вызовите метод recordImpression для соответствующего NativeCustomFormatAd :

myCustomFormatAd.recordImpression();

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

Сообщить о кликах

Чтобы сообщить SDK о том, что в представлении ресурса произошел щелчок, вызовите метод performClick для соответствующего NativeCustomFormatAd и передайте имя актива, по которому был выполнен щелчок. Например, если у вас есть ресурс в вашем пользовательском формате под названием «MainImage» и вы хотите сообщить о щелчке по ImageView , соответствующему этому активу, ваш код будет выглядеть следующим образом:

myCustomFormatAd.performClick("MainImage");

Обратите внимание: вам не нужно вызывать этот метод для каждого просмотра, связанного с вашим объявлением. Если у вас было другое поле под названием «Подпись», которое должно было отображаться, но не щелкалось и не касалось пользователем, вашему приложению не нужно было бы вызывать performClick для просмотра этого актива.

Реагировать на пользовательские действия по клику

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

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

Метод forCustomFormatAd принимает OnCustomClickListener . Если вы передаете объект прослушивателя, SDK вместо этого вызывает метод onCustomClick и не предпринимает никаких дальнейших действий. Однако если вы передадите нулевое значение в качестве прослушивателя, SDK вернется к глубоким ссылкам и/или целевым URL-адресам, зарегистрированным в объявлении.

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

Ява

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();

Котлин

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-адреса отслеживания, которые были установлены для креатива, и выполнять другие задачи «за кулисами» без какого-либо дополнительного кода.