Używanie niestandardowych formatów reklam natywnych

Oprócz zdefiniowanych przez system formatów natywnych wydawcy Ad Managera mogą tworzyć własne formaty reklam natywnych, definiując niestandardowe listy komponentów. Są to tzw. niestandardowe formaty reklam natywnych, których można używać w przypadku reklam z rezerwacji. Dzięki temu wydawcy mogą przekazywać do swoich aplikacji dowolne uporządkowane dane. Te reklamy są reprezentowane przez obiekt NativeCustomFormatAd.

Wczytywanie niestandardowych formatów reklam natywnych

Z tego przewodnika dowiesz się, jak wczytywać i wyświetlać niestandardowe formaty reklam natywnych.

Wczytywanie niestandardowej reklamy natywnej

Aby wczytać niestandardową reklamę natywną:

  1. Uwzględnij typ NativeAdType.CUSTOM_NATIVE jako typ reklamy w NativeAdRequest.

  2. Ustaw identyfikator formatu niestandardowej reklamy natywnej.

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

Identyfikator niestandardowego formatu reklamy natywnej

Identyfikator formatu używany do identyfikowania niestandardowego formatu reklamy natywnej można znaleźć w interfejsie Ad Managera w sekcji Natywne w menu Wyświetlanie:

Identyfikator każdego niestandardowego formatu reklamy natywnej jest widoczny obok jego nazwy. Kliknięcie jednej z nazw powoduje przejście do ekranu szczegółów, na którym wyświetlane są informacje o polach formatu:

W tym miejscu możesz dodawać, edytować i usuwać poszczególne pola. Zwróć uwagę na nazwę każdego zasobu. Nazwa to klucz używany do pobierania danych dla każdego komponentu podczas wyświetlania niestandardowego formatu reklamy natywnej.

Niestandardowe formaty reklam natywnych typu displayowego

Niestandardowe formaty reklam natywnych różnią się od formatów zdefiniowanych przez system tym, że wydawcy mogą definiować własną listę komponentów, z których składa się reklama. Dlatego proces wyświetlania takiego formatu różni się od formatów zdefiniowanych przez system na kilka sposobów:

  1. Komponenty tekstowe i komponenty z obrazem są dostępne za pomocą metod pobierających getText() i getImage(), które przyjmują nazwę pola jako parametr.
  2. Nie ma specjalnej klasy ViewGroup, którą można zarejestrować w Google, dlatego musisz ręcznie rejestrować wyświetlenia i kliknięcia.
  3. Niestandardowa reklama natywna ma treść multimedialną null, jeśli nie zawiera komponentu wideo.

Ten przykład pokazuje, jak wyświetlić 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();
  }
}

Natywne reklamy wideo w niestandardowych formatach reklam natywnych

Podczas tworzenia formatu niestandardowego możesz wybrać, czy ma on być dostępny w przypadku wideo.

W implementacji aplikacji możesz użyć CustomNativeAd.getMediaContent(), aby pobrać treści multimedialne. Następnie wywołaj metodę setMediaContent(), aby ustawić treści multimedialne w widoku multimediów. Jeśli reklama zawiera treści multimedialne (null), przygotuj alternatywne plany wyświetlania reklamy bez filmu.

W tym przykładzie sprawdzamy, czy reklama zawiera treści wideo, i wyświetlamy obraz, jeśli film jest niedostępny:

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

Więcej informacji o dostosowywaniu sposobu wyświetlania filmów w niestandardowych reklamach natywnych znajdziesz w artykule Reklamy wideo.

Renderowanie ikony Informacja

W ramach przestrzegania aktu o usługach cyfrowych (DSA) reklamy z rezerwacji wyświetlane w Europejskim Obszarze Gospodarczym (EOG) muszą zawierać ikonę Informacja i link do strony „O tej reklamie” w Google. Implementując niestandardowe reklamy natywne, odpowiadasz za renderowanie ikony Informacja. Zalecamy zadbanie o renderowanie i ustawienie detektora kliknięć ikony Informacja podczas renderowania głównych komponentów reklamy.

W poniższym przykładzie zakładamy, że w hierarchii widoków masz zdefiniowany element <ImageView />, który zawiera logo Informacja.

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

Poniższe przykłady pokazują, jak wyrenderować ikonę Informacja i skonfigurować odpowiednie działanie po kliknięciu.

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

Rejestrowanie wyświetleń i raportowanie kliknięć

Twoja aplikacja odpowiada za rejestrowanie wyświetleń i raportowanie zdarzeń kliknięcia do GMA Next-Gen SDK.

Rejestrowanie wyświetleń

Aby zarejestrować wyświetlenie niestandardowej reklamy natywnej, wywołaj metodę recordImpression() reklamy:

Kotlin

// Record an impression.
customNativeAd.recordImpression()

Java

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

Jeśli aplikacja przypadkowo wywoła metodę 2 razy dla tej samej reklamy, pakiet SDK automatycznie zapobiegnie zarejestrowaniu zduplikowanego wyświetlenia w przypadku pojedynczego żądania.

Kliknięcia raportów

Aby poinformować pakiet SDK, że nastąpiło kliknięcie widoku komponentu, wywołaj metodę performClick() reklamy. Podaj nazwę klikniętego komponentu, używając tego samego ciągu znaków, który został zdefiniowany w interfejsie Ad Managera.

Kotlin

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

Java

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

Pamiętaj, że nie musisz wywoływać tej metody w przypadku każdego widoku powiązanego z reklamą. Jeśli masz inne pole o nazwie „Podpis”, które ma być wyświetlane, ale nie ma być klikane przez użytkownika, aplikacja nie musi wywoływać metody performClick dla widoku tego komponentu.

Odpowiadanie na niestandardowe działania związane z kliknięciem

Gdy użytkownik kliknie reklamę w formacie niestandardowym, pakiet SDK może zareagować na 3 sposoby (w podanej kolejności):

  1. Wywołaj OnCustomClickListener, jeśli został podany.
  2. W przypadku każdego adresu URL precyzyjnego linku reklamy spróbuj znaleźć moduł rozpoznawania treści i uruchom pierwszy, który zostanie rozpoznany.
  3. Otwórz przeglądarkę i przejdź do docelowego adresu URL reklamy.

Aby wdrożyć niestandardowe działanie po kliknięciu, podaj 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.
      }
    });

Na początku może się wydawać, że niestandardowe detektory kliknięć są niepotrzebne. W końcu aplikacja właśnie poinformowała pakiet SDK o kliknięciu, więc dlaczego pakiet SDK miałby zgłaszać to aplikacji?

Ten przepływ informacji jest przydatny z kilku powodów, ale przede wszystkim umożliwia pakietowi SDK zachowanie kontroli nad odpowiedzią na kliknięcie. Może on na przykład automatycznie wysyłać pingi do linków monitorujących firm zewnętrznych, które zostały ustawione dla kreacji, i wykonywać inne zadania w tle bez dodatkowego kodu.