Niestandardowe formaty reklam natywnych

Niestandardowe formaty reklam natywnych

Oprócz formatów natywnych zdefiniowanych w systemie wydawcy korzystający z Ad Managera mogą tworzyć własne formaty reklam natywnych przez zdefiniowanie niestandardowych list zasobów. Nazywamy je niestandardowymi formatami natywnych reklam i można ich używać w przypadku reklam zarezerwowanych. Dzięki temu wydawcy mogą przekazywać do swoich aplikacji dowolne uporządkowane dane. Reklamy te są reprezentowane przez obiekt NativeCustomFormatAd.

Ładowanie niestandardowych formatów reklam natywnych

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

Tworzenie modułu AdLoader

Podobnie jak reklamy natywne, niestandardowe formaty reklam natywnych są wczytywane za pomocą klasy AdLoader:

Java

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

Kotlin

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

Metoda forCustomFormatAd konfiguruje AdLoader do wysyłania żądań dotyczących niestandardowych formatów reklam natywnych. Metoda ta ma 3 parametry:

  • Identyfikator niestandardowego formatu reklamy natywnej, którego AdLoader powinien zażądać. Z każdym niestandardowym formatem natywnej reklamy jest powiązany identyfikator. Ten parametr wskazuje, którego formatu aplikacja chce zażądać za pomocą AdLoader.
  • OnCustomFormatAdLoadedListener wywoływany po wczytaniu reklamy.
  • Opcjonalnie możesz ustawić OnCustomClickListener, aby wywołać tę funkcję po kliknięciu lub dotknięciu reklamy przez użytkownika. Więcej informacji o tym odbiorcy znajdziesz w sekcji „Przetwarzanie kliknięć i wyświetleń”.

Jedna jednostka reklamowa może zostać skonfigurowana tak, aby wyświetlała więcej niż 1 format kreacji, dlatego funkcja forCustomFormatAd może być wywoływana wiele razy z unikalnymi identyfikatorami formatów. Pozwala to przygotować moduł wczytujący reklamy do obsługi więcej niż jednego możliwego niestandardowego formatu reklamy natywnej.

Identyfikator niestandardowego formatu reklamy natywnej

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

Obok nazwy każdego niestandardowego formatu reklamy natywnej znajduje się jego identyfikator. Kliknięcie jednej z nazw wyświetli ekran szczegółów z informacjami o polach formatu:

Tutaj możesz dodawać, edytować i usuwać poszczególne pola. Zapisz nazwę każdego zasobu. Nazwa jest kluczem używanym do uzyskiwania danych o każdym komponencie podczas wyświetlania niestandardowego formatu reklamy natywnej.

Displayowe niestandardowe formaty reklam natywnych

Niestandardowe formaty reklam natywnych różnią się od zdefiniowanych przez system tym, że wydawcy mogą samodzielnie definiować listę komponentów reklamy. Dlatego proces wyświetlania takiego formatu różni się od procesów związanych z formatami zdefiniowanymi przez system w kilku aspektach:

  1. Klasa NativeCustomFormatAd jest przeznaczona do obsługi dowolnych niestandardowych formatów reklam natywnych zdefiniowanych w usłudze Ad Manager, dlatego nie ma nazwy „getters” dla zasobów. Zamiast tego oferuje metody takie jak getText i getImage, które przyjmują nazwę pola jako parametr.
  2. Nie ma specjalnej klasy widoku reklamy, takiej jak NativeAdView, która mogłaby być używana z NativeCustomFormatAd. Możesz wykorzystać dowolny układ, który odpowiada Twoim potrzebom.
  3. Ponieważ nie ma dedykowanej klasy ViewGroup, nie musisz rejestrować żadnego z widoków, których używasz do wyświetlania komponentów reklamy. Dzięki temu zaoszczędzisz kilka linii kodu podczas wyświetlania reklamy, ale będziesz też musiał później wykonać trochę dodatkowej pracy, aby obsłużyć kliknięcia.

Oto przykład funkcji, która wyświetla wartość 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.
    ...
}

Kotlin

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

Renderowanie ikony Informacja

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

W tym przykładzie zakładamy, że w hierarchii widoku zdefiniowano element <ImageView />, aby przechowywać w nim logo 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>

W przykladach poniżej renderujemy ikonę Informacja i konfigurujemy odpowiednie zachowanie po kliknięciu.

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

Kotlin

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

Natywny film w niestandardowych formatach reklam natywnych

Podczas tworzenia formatu niestandardowego możesz określić, czy ma on być odpowiedni do wyświetlania reklam wideo.

W implementacji aplikacji możesz użyć elementu NativeCustomFormatAd.getMediaContent(), aby pobrać treści multimedialne. Następnie wywołaj setMediaContent(), aby ustawić zawartość multimediów w widoku multimediów. Jeśli reklama nie zawiera treści wideo, utwórz alternatywne plany wyświetlania bez filmu.

Przykład poniżej sprawdza, czy reklama zawiera treści wideo, i wyświetla obraz, jeśli film nie jest dostępny:

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

Kotlin

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

Więcej informacji o dostosowywaniu wyświetlania filmów w niestandardowych reklamach natywnych znajdziesz w sekcji MediaContent.

Pobierz przykład renderowania niestandardowego w usłudze Ad Manager, aby zobaczyć przykład działania natywnej reklamy wideo.

Kliknięcia i wyświetlenia niestandardowego formatu reklamy natywnej

W przypadku niestandardowych formatów reklam natywnych aplikacja jest odpowiedzialna za rejestrowanie wyświetleń i zgłaszanie zdarzeń kliknięcia do pakietu SDK do reklam mobilnych Google.

Rejestrowanie wyświetleń

Aby zarejestrować wyświetlenie reklamy w formacie niestandardowym, wywołaj metodę recordImpression w odpowiednim elemencie NativeCustomFormatAd:

myCustomFormatAd.recordImpression();

Jeśli Twoja aplikacja przypadkowo wywoła metodę dwukrotnie w przypadku tej samej reklamy, SDK automatycznie uniemożliwi zarejestrowanie zduplikowanego wyświetlenia w ramach pojedynczego żądania.

Raportowanie kliknięć

Aby zgłosić do SDK, że kliknięcie nastąpiło w przypadku wyświetlenia zasobu, wywołaj metodę performClick na odpowiednim obiekcie NativeCustomFormatAd i przekaż nazwę zasobu, który został kliknięty. Jeśli np. masz zasób w formacie niestandardowym o nazwie „MainImage” i chcesz zgłaszać kliknięcia na ImageView odpowiadające temu zasobowi, Twój kod będzie wyglądać tak:

myCustomFormatAd.performClick("MainImage");

Pamiętaj, że nie musisz wywoływać tej metody w przypadku każdego wyświetlenia powiązanego z Twoją reklamą. Gdyby było inne pole o nazwie „Podpis”, które miało się wyświetlać, ale nie było klikane przez użytkownika, aplikacja nie musi wywoływać funkcji performClick, by wyświetlić ten zasób.

Odpowiedź na niestandardowe działania po kliknięciu

Gdy użytkownik kliknie reklamę w formacie niestandardowym, pakiet SDK może udzielić 3 odpowiedzi w tej kolejności:

  1. Wywołaj funkcję OnCustomClickListener z metody AdLoader, jeśli została podana.
  2. W przypadku każdego adresu URL precyzyjnego linku reklamy spróbuj znaleźć usługę rozwiązywania treści i uruchom pierwszą, która się rozwiąże.
  3. Otwórz przeglądarkę i otwórz tradycyjny adres URL docelowy reklamy.

Metoda forCustomFormatAd przyjmuje argument OnCustomClickListener. Jeśli przekazujesz obiekt listenera, pakiet SDK wywołuje zamiast tego metodę onCustomClick i nie podejmuje żadnych dalszych działań. Jeśli jednak jako parametr listenera podasz wartość null, pakiet SDK użyje linku docelowego lub adresów URL docelowych zarejestrowanych w reklamie.

Słuchacze kliknięć niestandardowych umożliwiają aplikacji wybranie najlepszego działania w odpowiedzi na kliknięcie, np. zaktualizowanie interfejsu użytkownika, uruchomienie nowej aktywności lub po prostu odnotowanie kliknięcia. Oto przykład, który po prostu rejestruje kliknięcie:

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

Kotlin

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

Na początku może się wydawać dziwne, że istnieją niestandardowe odbiorniki kliknięć. W końcu Twoja aplikacja właśnie poinformowała pakiet SDK o tym, że kliknięcie nastąpiło, więc dlaczego pakiet SDK miałby zgłaszać to aplikacji?

Ten przepływ informacji jest przydatny z kilku powodów, ale najważniejszym jest to, że pozwala pakietowi SDK zachować kontrolę nad odpowiedzią na kliknięcie. Może on automatycznie wysyłać zapytania do zewnętrznych adresów URL służących do śledzenia, które zostały określone np. dla kreacji, i wykonywać inne zadania w tle bez dodatkowego kodu.