Niestandardowe formaty reklam natywnych

Niestandardowe formaty reklam natywnych

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

Wczytaj niestandardowe formaty reklam natywnych

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

Tworzenie modułu AdLoader

Podobnie jak w przypadku reklam natywnych niestandardowe formaty reklam natywnych są wczytywane za pomocą klasy AdLoader:

Java

AdLoader adLoader = new AdLoader.Builder(context, "/6499/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, "/6499/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 pod kątem żądań niestandardowych formatów reklam natywnych. Do metody trafiają 3 parametry:

• Identyfikator niestandardowego formatu reklamy natywnej, do którego AdLoader ma mieć żądanie. Z każdym niestandardowym formatem reklamy natywnej jest powiązany identyfikator. Wskazuje on format, do którego aplikacja AdLoader ma wysyłać żądania.
• OnCustomFormatAdLoadedListener, który ma być wywoływany po pomyślnym wczytaniu reklamy.
• Opcjonalny obiekt OnCustomClickListener, który jest wywoływany, gdy użytkownik kliknie reklamę. Więcej o tym narzędziu znajdziesz w sekcji „Obsługa kliknięć i wyświetleń” poniżej.

Pojedynczą jednostkę reklamową można skonfigurować do wyświetlania więcej niż 1 formatu kreacji, dlatego komponent forCustomFormatAd można wywoływać kilka razy z unikalnymi identyfikatorami formatów. Pozwala to przygotować program wczytujący reklamę na potrzeby kilku możliwych niestandardowych formatów reklamy natywnej.

Uwaga: elementów forNativeAd i forCustomFormatAd można używać jednocześnie z pojedynczym elementem AdLoader, jeśli masz jednostkę reklamową skonfigurowaną do wyświetlania wielu formatów reklam.

Identyfikator niestandardowego formatu reklamy natywnej

Identyfikator formatu służący do identyfikowania niestandardowego formatu reklamy natywnej znajdziesz w interfejsie Ad Managera w sekcji Natywna w menu Wyświetlanie:

Każdy identyfikator niestandardowego formatu reklamy natywnej jest widoczny obok jego nazwy. Kliknij jedną z nazw, aby 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 służy do pobierania danych o poszczególnych zasobach podczas wyświetlania niestandardowego formatu reklamy natywnej.

Niestandardowe formaty reklam natywnych w sieci reklamowej

Niestandardowe formaty reklam natywnych różnią się od tych zdefiniowanych w systemie tym, że wydawcy mogą definiować własne listy zasobów, z których składa się reklama. Dlatego proces wyświetlania tych formatów różni się od formatów zdefiniowanych przez system pod kilkoma względami:

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 udostępnia metody takie jak getText i getImage, które przyjmują nazwę pola jako parametr.
2. Nie ma dedykowanej klasy widoku reklamy, takiej jak NativeAdView, której można użyć w projekcie NativeCustomFormatAd. Możesz używać dowolnego układu, który pasuje do wygody użytkowników.
3. Nie ma dedykowanej klasy ViewGroup, więc nie musisz rejestrować żadnych widoków danych używanych do wyświetlania komponentów reklamy. Pozwala to zaoszczędzić kilka wierszy kodu podczas wyświetlania reklamy, ale trzeba też wykonać kilka dodatkowych czynności, aby obsługiwać kliknięcia.

Oto przykładowa funkcja, która wyświetla 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 aktu prawnego o usługach cyfrowych (DSA) reklamy z rezerwacji wyświetlane w Europejskim Obszarze Gospodarczym (EOG) wymagają ikony Informacja i linku do strony „Informacje o tej reklamie” w Google. Implementując niestandardowe reklamy natywne, odpowiadasz za renderowanie ikony Informacja. Zalecamy renderowanie i ustawianie nasłuchiwania kliknięć ikony Informacja podczas renderowania głównych zasobów reklamy.

W tym przykładzie założono, że w hierarchii widoków zdefiniowany jest element <ImageView />, który służy do przechowywania logo Informacja.

Ważne: ustaw ikonę Informacja o wymiarach co najmniej 15 x 15 pikseli.

<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 podanych niżej przykładach renderujemy ikonę Informacja i konfigurujemy odpowiednie zachowanie związane z klikaniem.

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

Ważne: jeśli używasz kontrolki do pobierania obrazów, aby żądać tylko adresów URL obrazów, komponent Informacja będzie uwzględniał to ustawienie i zwraca tylko adres URL obrazu.

Natywne formaty wideo do niestandardowych formatów reklam natywnych

Podczas tworzenia formatu niestandardowego możesz go udostępnić dla wideo.

W implementacji aplikacji możesz pobrać treści multimedialne za pomocą metody NativeCustomFormatAd.getMediaContent(). Następnie wywołaj setMediaContent(), aby ustawić treści multimedialne w widoku multimediów na widok multimediów. Jeśli reklama nie zawiera treści wideo, zaplanuj alternatywne plany, by wyświetlać reklamę bez filmu.

Uwaga: w przeciwieństwie do reklam natywnych, które zawierają obraz w widoku multimediów, gdy film jest niedostępny, widok multimediów niestandardowej reklamy natywnej nie zawiera treści, jeśli nie zawiera filmu.

Poniższy przykład pokazuje, czy reklama zawiera treści wideo i wyświetla w jej miejscu obraz, jeśli film jest niedostę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)
  }
}

W sekcji MediaContent znajdziesz więcej informacji o dostosowywaniu sposobu wyświetlania reklam wideo w niestandardowej reklamie natywnej.

Pobierz przykład renderowania niestandardowego w usłudze Ad Manager, aby zobaczyć przykład działania natywnych reklam wideo w działaniu.

Kliknięcia i wyświetlenia niestandardowego formatu reklamy natywnej

W przypadku niestandardowych formatów reklam natywnych aplikacja odpowiada za rejestrowanie wyświetleń i raportowanie zdarzeń kliknięć w pakiecie 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 aplikacja przypadkowo wywoła tę metodę 2 razy w przypadku tej samej reklamy, pakiet SDK automatycznie zapobiega rejestrowaniu zduplikowanego wyświetlenia w przypadku pojedynczego żądania.

Zgłaszanie kliknięć

Aby poinformować pakiet SDK o wystąpieniu kliknięcia w wyświetleniu zasobu, wywołaj metodę performClick w odpowiednim elemencie NativeCustomFormatAd i przekaż nazwę klikniętego zasobu. Jeśli np. masz zasób w formacie niestandardowym o nazwie „MainImage” i chcesz zgłosić kliknięcie elementu ImageView powiązanego z tym zasobem, kod będzie wyglądać tak:

myCustomFormatAd.performClick("MainImage");

Pamiętaj, że nie musisz wywoływać tej metody w przypadku każdego widoku danych powiązanego z Twoją reklamą. Jeśli masz inne pole o nazwie „Podpis”, które miało być wyświetlane, ale nie zostało kliknięte przez użytkownika, aplikacja nie musi wywoływać funkcji performClick, aby wyświetlić ten zasób.

Reagowanie na działania związane z kliknięciami niestandardowymi

Po kliknięciu reklamy o niestandardowym formacie pakiet SDK może zareagować na 3 sposoby w tej kolejności:

1. Wywołaj funkcję OnCustomClickListener z metody AdLoader, jeśli została podana.
2. W przypadku każdego adresu URL precyzyjnych linków w reklamie znajdź program do rozpoznawania treści i uruchom pierwszy, który rozwiąże problem.
3. Otwórz przeglądarkę i przejdź do tradycyjnego docelowego adresu URL reklamy.

Metoda forCustomFormatAd akceptuje OnCustomClickListener. Jeśli prześlesz obiekt nasłuchującego, pakiet SDK wywoła metodę onCustomClick i nie podejmie dalszych działań. Jeśli jednak jako detektor przekażesz wartość null, pakiet SDK użyje precyzyjnego linku lub docelowych adresów URL zarejestrowanych w reklamie.

Niestandardowe detektory kliknięć pozwalają aplikacji zdecydować, jakie działanie powinna podjąć w odpowiedzi na kliknięcie – może to być aktualizacja interfejsu, uruchomienie nowej aktywności czy tylko zarejestrowanie kliknięcia. Oto przykład, który po prostu rejestruje miejsce wystąpienia kliknięcia:

Java

AdLoader adLoader = new AdLoader.Builder(context, "/6499/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, "/6499/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 detektory kliknięć. Twoja aplikacja właśnie informowała pakiet SDK o kliknięciu. Dlaczego więc powinien on wycofać i zgłosić to do aplikacji?

Ten przepływ informacji jest przydatny z kilku powodów, ale przede wszystkim pozwala SDK zachować kontrolę nad reakcją na kliknięcie. Może np. automatycznie wysyłać pingi do linków monitorujących firm zewnętrznych, które zostały ustawione dla kreacji, i wykonywać w tle inne zadania bez konieczności pisania dodatkowego kodu.