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

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

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

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

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

Загрузить пользовательскую нативную рекламу

Как и нативная реклама, пользовательские форматы нативной рекламы загружаются с помощью класса 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();

Котлин 

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

Идентификатор пользовательского формата нативной рекламы

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

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

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

Отображение пользовательских форматов нативной рекламы

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

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

Вот пример функции, которая отображает 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.
    ...
}

Котлин 

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

Котлин 

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

Загрузите пример пользовательского рендеринга в Ad Manager, чтобы увидеть работающую демонстрацию нативного видео.

Дополнительную информацию о том, как настроить видеоконтент в пользовательской нативной рекламе, см. в разделе «Видеореклама» .

Отобразить значок AdChoices

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

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

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

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

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

Котлин 

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

Записывайте показы и составляйте отчеты по кликам.

Ваше приложение отвечает за запись показов и передачу данных о кликах в Google Mobile Ads SDK.

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

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

myCustomFormatAd.recordImpression();

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

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

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

myCustomFormatAd.performClick("MainImage");

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

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

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

  1. Вызовите обработчик OnCustomClickListener , если он был предоставлен.
  2. Для каждой из прямых ссылок в рекламе попытайтесь найти обработчик контента и запустите первый, который его обнаружит.
  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();

Котлин 

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