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

Помимо стандартных форматов нативных объявлений, издатели Менеджера рекламы могут создавать собственные форматы, задавая списки объектов. Такие форматы называются специальными форматами нативных объявлений и могут использоваться с зарезервированными объявлениями. Это позволяет издателям передавать в свои приложения любые структурированные данные. Такие объявления представлены объектом 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. В нативных объявлениях, которые появляются в приложениях, должен показываться значок "Выбор рекламы". Ответственность за это несете вы. Настоятельно рекомендуем вам отображать значок "Выбор рекламы" и устанавливать для него прослушиватель кликов при отрисовке основных объектов объявлений.

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

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