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

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

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

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

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

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

  1. Добавьте тип NativeAdType.CUSTOM_NATIVE в качестве типа объявления в NativeAdRequest.

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

Kotlin

val adRequest =
  NativeAdRequest.Builder("AD_UNIT_ID", listOf(NativeAdType.CUSTOM_NATIVE))
    .setCustomFormatIds(listOf("CUSTOM_NATIVE_FORMAT_ID"))
    .build()

// Load the native ad with the ad request and callback.
NativeAdLoader.load(
  adRequest,
  object : NativeAdLoaderCallback {
    override fun onCustomNativeAdLoaded(customNativeAd: CustomNativeAd) {
      // TODO: Store the custom native ad.
    }

    override fun onAdFailedToLoad(adError: LoadAdError) {}
  },
)

Java

NativeAdRequest adRequest =
    new NativeAdRequest.Builder("AD_UNIT_ID", List.of(NativeAd.NativeAdType.CUSTOM_NATIVE))
        .setCustomFormatIds(Arrays.asList("CUSTOM_NATIVE_FORMAT_ID"))
        .build();

// Load the native ad with the ad request and callback.
NativeAdLoader.load(
    adRequest,
    new NativeAdLoaderCallback() {
      @Override
      public void onCustomNativeAdLoaded(@NonNull CustomNativeAd customNativeAd) {
        // TODO: Store the custom native ad.
      }

      @Override
      public void onAdFailedToLoad(@NonNull LoadAdError adError) {}
    });

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

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

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

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

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

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

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

В примере ниже показано, как отобразить CustomNativeAd:

Kotlin

private fun displayCustomNativeAd(customNativeAd: CustomNativeAd, context: Context) {
  // Render the text elements.

  // The `customNativeAdBinding` is the layout binding for the ad container that
  // contains all `CustomNativeAd` assets.
  customNativeAdBinding.headline.text = customNativeAd.getText("Headline")
  customNativeAdBinding.caption.text = customNativeAd.getText("Caption")

  // If the main asset is an image, render it with an ImageView.
  val imageView = ImageView(context)
  imageView.adjustViewBounds = true
  imageView.setImageDrawable(customNativeAd.getImage("MainImage")?.drawable)
  imageView.setOnClickListener { customNativeAd.performClick("MainImage") }
  customNativeAdBinding.mediaPlaceholder.addView(imageView)

  // Render the ad choices icon.
  renderAdChoices(customNativeAd)

  // Record an impression.
  customNativeAd.recordImpression()
}

Java

private void displayCustomNativeAd(CustomNativeAd customNativeAd, Context context) {
  // Render the text elements.

  // The `customNativeAdBinding` is the layout binding for the ad container that
  // contains all `CustomNativeAd` assets.
  if (customNativeAdBinding != null) {
    customNativeAdBinding.headline.setText(customNativeAd.getText("Headline"));
    customNativeAdBinding.caption.setText(customNativeAd.getText("Caption"));

    ImageView imageView = new ImageView(context);
    imageView.setAdjustViewBounds(true);
    imageView.setImageDrawable(customNativeAd.getImage("MainImage").getDrawable());
    imageView.setOnClickListener(
        new View.OnClickListener() {
          @Override
          public void onClick(View v) {
            customNativeAd.performClick("MainImage");
          }
        });
    customNativeAdBinding.mediaPlaceholder.addView(imageView);

    // Render the ad choices icon.
    renderAdChoices(customNativeAd);

    // Record an impression.
    customNativeAd.recordImpression();
  }
}

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

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

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

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

Kotlin

private fun displayVideoCustomNativeAd(customNativeAd: CustomNativeAd, context: Context) {
  // Check whether the custom native ad has video content.
  val mediaContent = customNativeAd.mediaContent
  if (mediaContent != null && mediaContent.hasVideoContent) {
    // Render the media content in a MediaView.
    val mediaView = MediaView(context)
    mediaView.mediaContent = mediaContent
    customNativeAdBinding.mediaPlaceholder.addView(mediaView)
  } else {
    // Fall back to other assets defined on your custom native ad.
    val imageView = ImageView(context)
    imageView.adjustViewBounds = true
    imageView.setImageDrawable(customNativeAd.getImage("MainImage")?.drawable)
    customNativeAdBinding.mediaPlaceholder.addView(imageView)
  }

  // Record an impression.
  customNativeAd.recordImpression()
}

Java

private void displayVideoCustomNativeAd(CustomNativeAd customNativeAd, Context context) {
  // Check whether the custom native ad has video content.
  MediaContent mediaContent = customNativeAd.getMediaContent();
  if (mediaContent != null && mediaContent.getHasVideoContent()) {
    // Render the media content in a MediaView.
    MediaView mediaView = new MediaView(context);
    mediaView.setMediaContent(mediaContent);
    customNativeAdBinding.mediaPlaceholder.addView(mediaView);
  } else {
    // Fall back to other assets defined on your custom native ad.
    ImageView imageView = new ImageView(context);
    imageView.setAdjustViewBounds(true);
    imageView.setImageDrawable(customNativeAd.getImage("MainImage").getDrawable());
    customNativeAdBinding.mediaPlaceholder.addView(imageView);
  }

  // Record an impression.
  customNativeAd.recordImpression();
}

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

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

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

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

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

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

Kotlin

private fun renderAdChoices(customNativeAd: CustomNativeAd) {
  // Render the AdChoices image.
  val adChoiceAsset = customNativeAd.getImage(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW)
  if (adChoiceAsset != null) {
    customNativeAdBinding.adchoices.setImageDrawable(adChoiceAsset.drawable)
    customNativeAdBinding.adchoices.visibility = View.VISIBLE
    customNativeAdBinding.adchoices.setOnClickListener {
      // Handle click. See the next section for more details.
      customNativeAd.performClick(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW)
    }
  } else {
    customNativeAdBinding.adchoices.visibility = View.GONE
  }
}

Java

private void renderAdChoices(CustomNativeAd customNativeAd) {
  // Render the AdChoices image.
  Image adChoiceAsset =
      customNativeAd.getImage(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW);
  if (adChoiceAsset != null) {
    if (customNativeAdBinding != null) {
      customNativeAdBinding.adchoices.setImageDrawable(adChoiceAsset.getDrawable());
      customNativeAdBinding.adchoices.setVisibility(View.VISIBLE);
      customNativeAdBinding.adchoices.setOnClickListener(
          new View.OnClickListener() {
            @Override
            public void onClick(View v) {
              // Handle click.
              customNativeAd.performClick(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW);
            }
          });
    }
  } else {
    if (customNativeAdBinding != null) {
      customNativeAdBinding.adchoices.setVisibility(View.GONE);
    }
  }
}

Регистрировать показы и сообщать о кликах

Ваше приложение должно регистрировать показы и сообщать о кликах в GMA Next-Gen SDK.

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

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

Kotlin

// Record an impression.
customNativeAd.recordImpression()

Java

// Record an impression.
customNativeAd.recordImpression();

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

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

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

Kotlin

imageView.setOnClickListener { customNativeAd.performClick("MainImage") }

Java

imageView.setOnClickListener(
    new View.OnClickListener() {
      @Override
      public void onClick(View v) {
        customNativeAd.performClick("MainImage");
      }
    });

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

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

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

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

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

Kotlin

customNativeAd.onCustomClickListener =
  object : OnCustomClickListener {
    override fun onCustomClick(assetName: String) {
      // Perform your custom action.
    }
  }

Java

customNativeAd.setOnCustomClickListener(
    new OnCustomClickListener() {
      @Override
      public void onCustomClick(@NonNull String assetName) {
        // Perform your custom action.
      }
    });

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

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