Benutzerdefinierte Formate für native Anzeigen

Benutzerdefinierte native Anzeigenformate

Zusätzlich zu den systemdefinierten nativen Formaten haben Ad Manager-Publisher die Möglichkeit, eigene native Anzeigenformate zu erstellen, indem sie benutzerdefinierte Listen von Assets definieren. Diese werden als benutzerdefinierte native Anzeigenformate bezeichnet und können mit reservierten Anzeigen verwendet werden. Dadurch können Publisher beliebige strukturierte Daten an ihre Apps übergeben. Für diese Anzeigen wird das Objekt NativeCustomFormatAd verwendet.

Benutzerdefinierte native Anzeigenformate laden

In diesem Leitfaden erfahren Sie, wie benutzerdefinierte native Anzeigenformate geladen und ausgeliefert werden.

AdLoader erstellen

Wie native Anzeigen werden benutzerdefinierte native Anzeigenformate mit der Klasse AdLoader geladen:

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

Mit der Methode forCustomFormatAd wird die AdLoader konfiguriert, um benutzerdefinierte native Anzeigenformate anzufordern. Der Methode werden drei Parameter übergeben:

• Die ID des benutzerdefinierten nativen Anzeigenformats, das von AdLoader angefordert werden soll. Jedem benutzerdefinierten nativen Anzeigenformat ist eine ID zugeordnet. Dieser Parameter gibt an, welches Format die Anwendung von AdLoader anfordern soll.
• Ein OnCustomFormatAdLoadedListener, das aufgerufen wird, wenn eine Anzeige geladen wurde.
• Ein optionales OnCustomClickListener-Element, das aufgerufen wird, wenn der Nutzer auf die Anzeige tippt oder klickt. Weitere Informationen zu diesem Listener finden Sie unten im Abschnitt "Klicks und Impressionen verarbeiten".

Da ein einzelner Anzeigenblock für die Auslieferung mehrerer Creative-Formate konfiguriert werden kann, kann forCustomFormatAd mehrmals mit eindeutigen Format-IDs aufgerufen werden, um AdLoader für mehrere mögliche benutzerdefinierte native Anzeigenformate vorzubereiten.

Hinweis :forNativeAd und forCustomFormatAd können gleichzeitig mit einem einzelnen AdLoader verwendet werden, wenn Sie einen Anzeigenblock haben, der für die Auslieferung mehrerer Anzeigenformate konfiguriert ist.

ID des benutzerdefinierten nativen Anzeigenformats

Die Format-ID, mit der ein benutzerdefiniertes natives Anzeigenformat identifiziert wird, finden Sie auf der Ad Manager-Benutzeroberfläche im Drop-down-Menü Auslieferung im Bereich Nativ:

Die einzelnen IDs für benutzerdefinierte native Anzeigenformate sind neben dem Namen zu sehen. Wenn Sie auf einen der Namen klicken, gelangen Sie zu einem Bildschirm mit Informationen zu den Feldern des Formats:

Hier können einzelne Felder hinzugefügt, bearbeitet und entfernt werden. Notieren Sie sich den Namen der einzelnen Assets. Der Name ist der Schlüssel zum Abrufen der Daten für jedes Asset, wenn Ihr benutzerdefiniertes natives Anzeigenformat ausgeliefert wird.

Benutzerdefinierte native Anzeigenformate für Displayanzeigen

Benutzerdefinierte native Anzeigenformate unterscheiden sich von systemdefinierten, da Publisher ihre eigene Liste der Assets definieren können, aus denen eine Anzeige besteht. Daher unterscheidet sich der Vorgang zum Anzeigen eines solchen Formats in einigen Punkten von systemdefinierten Formaten:

1. Da die Klasse NativeCustomFormatAd dazu gedacht ist, alle benutzerdefinierten nativen Anzeigenformate zu verarbeiten, die Sie in Ad Manager definieren, hat sie keine benannten Abrufmethoden (Getter) für Assets. Stattdessen bietet er Methoden wie getText und getImage, die den Namen des Felds als Parameter annehmen.
2. Es gibt keine dedizierte Anzeigenansichtsklasse wie NativeAdView zur Verwendung mit NativeCustomFormatAd. Sie können jedes Layout verwenden, das für Ihre User Experience am sinnvollsten ist.
3. Da es keine dedizierte ViewGroup-Klasse gibt, müssen Sie keine der Ansichten registrieren, die Sie zum Ausliefern der Assets der Anzeige verwenden. Dadurch wird beim Ausliefern der Anzeige einige Codezeilen eingespart. Es ist aber auch ein wenig zusätzlicher Aufwand verbunden, um später Klicks zu verarbeiten.

Hier sehen Sie eine Beispielfunktion, die ein NativeCustomFormatAd anzeigt:

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

Native Videoanzeigen für benutzerdefinierte native Anzeigenformate

Beim Erstellen eines benutzerdefinierten Formats können Sie festlegen, dass das Format für Videos geeignet ist.

In der App-Implementierung können Sie mit NativeCustomFormatAd.getMediaContent() die Medieninhalte abrufen. Rufen Sie dann setMediaContent() auf, um den Medieninhalt in Ihrer Medienansicht auf Ihre Medienansicht einzustellen. Wenn die Anzeige keine Videoinhalte enthält, sollten Sie alternative Pläne für die Auslieferung der Anzeige ohne Video erarbeiten.

Hinweis :Im Gegensatz zu nativen Anzeigen, die in der Mediaansicht ein Bild enthalten, wenn kein Video verfügbar ist, hat die Medienansicht einer benutzerdefinierten nativen Anzeige keinen Inhalt, wenn sie kein Video enthält.

Im folgenden Beispiel wird geprüft, ob die Anzeige Videoinhalte enthält. Wenn kein Video verfügbar ist, wird stattdessen ein Bild eingeblendet:

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

Unter MediaContent finden Sie weitere Informationen dazu, wie Sie die Darstellung einer benutzerdefinierten nativen Anzeige anpassen.

Laden Sie das Beispiel für das benutzerdefinierte Rendering von Ad Manager herunter, um ein funktionierendes Beispiel für ein natives Video in Aktion zu erhalten.

Klicks und Impressionen für benutzerdefinierte native Anzeigenformate

Bei benutzerdefinierten nativen Anzeigenformaten ist Ihre App für das Erfassen von Impressionen und das Melden von Klickereignissen an das Google Mobile Ads SDK zuständig.

Impressionen erfassen

Wenn Sie eine Impression für eine Anzeige mit benutzerdefiniertem Format erfassen möchten, rufen Sie die Methode recordImpression für die entsprechende NativeCustomFormatAd auf:

myCustomFormatAd.recordImpression();

Wenn Ihre App die Methode versehentlich zweimal für dieselbe Anzeige aufruft, verhindert das SDK automatisch, dass für eine einzelne Anfrage eine doppelte Impression erfasst wird.

Klicks erfassen

Wenn Sie dem SDK melden möchten, dass bei einer Asset-Ansicht ein Klick aufgetreten ist, rufen Sie die Methode performClick für die entsprechende NativeCustomFormatAd auf und übergeben Sie den Namen des Assets, auf das geklickt wurde. Wenn beispielsweise ein Asset in Ihrem benutzerdefinierten Format namens „MainImage“ vorliegt und Sie einen Klick auf das ImageView melden möchten, das diesem Asset entspricht, würde Ihr Code so aussehen:

myCustomFormatAd.performClick("MainImage");

Sie müssen diese Methode nicht für jede Ansicht aufrufen, die Ihrer Anzeige zugeordnet ist. Wenn Sie ein weiteres Feld namens „Untertitel“ haben, das angezeigt, aber vom Nutzer nicht angeklickt oder angetippt werden sollte, muss in Ihrer App performClick für die Ansicht dieses Assets nicht aufgerufen werden.

Auf benutzerdefinierte Klickaktionen reagieren

Wenn auf eine Anzeige im benutzerdefinierten Format geklickt wird, gibt es drei mögliche Antworten vom SDK, die in dieser Reihenfolge versucht werden:

1. Rufen Sie OnCustomClickListener aus AdLoader auf, falls eine angegeben wurde.
2. Suchen Sie für jede Deeplink-URL der Anzeige einen Content-Resolver und starten Sie den ersten aufgelösten Content-Resolver.
3. Öffnen Sie einen Browser und navigieren Sie zur herkömmlichen Ziel-URL der Anzeige.

Die Methode forCustomFormatAd akzeptiert einen OnCustomClickListener. Wenn Sie ein Listener-Objekt übergeben, ruft das SDK stattdessen die Methode onCustomClick auf und unternimmt keine weiteren Aktionen. Wenn Sie als Listener einen Nullwert übergeben, verwendet das SDK jedoch den Deeplink und/oder die Ziel-URLs, die für die Anzeige registriert sind.

Mit benutzerdefinierten Klick-Listenern kann Ihre Anwendung entscheiden, welche Aktion als Reaktion auf einen Klick am besten ausgeführt werden soll. Dabei kann es sich um das Aktualisieren der UI, das Starten einer neuen Aktivität oder das Logging des Klicks handeln. Im folgenden Beispiel wird lediglich protokolliert, dass ein Klick erfolgt ist:

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

Auf den ersten Blick mag es seltsam erscheinen, dass es benutzerdefinierte Klick-Listener gibt. Schließlich hat Ihre App dem SDK gerade mitgeteilt, dass ein Klick aufgetreten ist. Warum sollte das SDK dann den Vorgang ausführen und dies an die App melden?

Dieser Informationsfluss ist aus verschiedenen Gründen nützlich. Vor allem aber ermöglicht er dem SDK, die Kontrolle über die Reaktion auf den Klick zu behalten. Sie kann beispielsweise Tracking-URLs von Drittanbietern, die für das Creative festgelegt wurden, automatisch anpingen und andere Aufgaben im Hintergrund ohne zusätzlichen Code ausführen.