Benutzerdefinierte native Anzeigenformate verwenden

Plattform auswählen: Android (Beta) Neu Android iOS

Zusätzlich zu den vom System definierten nativen Formaten können Ad Manager-Publisher eigene native Anzeigenformate erstellen, indem sie benutzerdefinierte Listen von Assets definieren. Diese werden als benutzerdefinierte native Anzeigen formate bezeichnet und können mit reservierten Anzeigen verwendet werden. So können Publisher beliebige strukturierte Daten an ihre Apps weitergeben. Diese Anzeigen werden durch das NativeCustomFormatAd Objekt dargestellt.

Benutzerdefinierte native Anzeigenformate laden

In dieser Anleitung wird erläutert, wie Sie benutzerdefinierte native Anzeigenformate laden und anzeigen.

Benutzerdefinierte native Anzeigen laden

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

Java

AdLoader adLoader = new AdLoader.Builder(this, "/21775744923/example/native")
    .forCustomFormatAd("12387226",
        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
          }
        })
    .forCustomFormatAd("12406343",
        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
          }
        })
    .build();

Kotlin

val adLoader = AdLoader.Builder(this, "/21775744923/example/native")
  .forCustomFormatAd(
    "12387226",
    { customFormatAd ->
      // Show the custom format and record an impression.
    },
    { customFormatAd, s ->
      // Handle the click action
    })
  .forCustomFormatAd(
    "12406343",
    { customFormatAd ->
      // Show the custom format and record an impression.
    },
    { customFormatAd, s ->
      // Handle the click action
    })
  .build()

Mit der Methode forCustomFormatAd wird der AdLoader so konfiguriert, dass er benutzerdefinierte native Anzeigenformate anfordert. Sie können die Methode mehrmals für verschiedene benutzerdefinierte Format-IDs aufrufen. Die Methode akzeptiert die folgenden Parameter:

  • Die ID des benutzerdefinierten nativen Anzeigenformats, das der AdLoader anfordern soll. Jedes benutzerdefinierte native Anzeigenformat hat eine ID. Dieser Parameter gibt an, welches Format Ihre App vom AdLoader anfordern soll.
  • Ein OnCustomFormatAdLoadedListener , der aufgerufen wird, wenn eine Anzeige erfolgreich geladen wurde.
  • Ein optionaler OnCustomClickListener , der aufgerufen wird, wenn der Nutzer auf die Anzeige tippt oder klickt. Weitere Informationen zu diesem Listener finden Sie im Abschnitt Klicks und Impressionen verarbeiten.

Da ein einzelner Anzeigenblock so eingerichtet werden kann, dass er mehr als ein Creative-Format ausliefert, kann forCustomFormatAd mehrmals mit eindeutigen Format-IDs aufgerufen werden, um den Anzeigenlader für mehr als ein mögliches benutzerdefiniertes natives Anzeigenformat vorzubereiten.

ID des benutzerdefinierten nativen Anzeigenformats

Die Format-ID, die zum Identifizieren eines benutzerdefinierten nativen Anzeigenformats verwendet wird, finden Sie in der Ad Manager-Benutzeroberfläche im Drop-down-Menü Auslieferung im Bereich Nativ:

Jede ID des benutzerdefinierten nativen Anzeigenformats wird neben dem Namen angezeigt. Wenn Sie auf einen der Namen klicken, gelangen Sie zu einem Detailbildschirm mit Informationen zu den Feldern des Formats:

Hier können einzelne Felder hinzugefügt, bearbeitet und entfernt werden. Beachten Sie den Namen der einzelnen Assets. Der Name ist der Schlüssel, der verwendet wird, um die Daten für jedes Asset abzurufen, wenn Sie Ihr benutzerdefiniertes natives Anzeigenformat anzeigen.

Benutzerdefinierte native Anzeigenformate anzeigen

Benutzerdefinierte native Anzeigenformate unterscheiden sich von den vom System definierten Formaten dadurch, dass Publisher ihre eigene Liste von Assets definieren können, aus denen eine Anzeige besteht. Daher unterscheidet sich der Prozess zum Anzeigen eines solchen Formats in einigen Punkten von dem für vom System definierte Formate:

  1. Text- und Bild-Assets sind über die Getter getText() und getImage() verfügbar, die den Feldnamen als Parameter verwenden.
  2. Da es keine spezielle ViewGroup-Klasse gibt, die bei Google registriert werden kann, müssen Sie Impressionen und Klicks manuell erfassen.
  3. Eine benutzerdefinierte native Anzeige hat einen null-Medieninhalt, wenn sie kein Video-Asset enthält.

Hier ist ein Beispiel für eine Funktion, die eine 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.
    ...
}

Natives Video für benutzerdefinierte native Anzeigenformate

Wenn Sie ein benutzerdefiniertes Format erstellen, können Sie es für Videos aktivieren.

In Ihrer App-Implementierung können Sie NativeCustomFormatAd.getMediaContent() verwenden, um den Medieninhalt abzurufen. Rufen Sie dann setMediaContent() auf, um den Medieninhalt in Ihrer Medienansicht festzulegen. Wenn die Anzeige einen null-Medieninhalt hat, planen Sie eine alternative Möglichkeit, die Anzeige ohne Video zu präsentieren.

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

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

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

Weitere Informationen zum Anpassen der Videoanzeigen für benutzerdefinierte native Anzeigen finden Sie unter Videoanzeigen.

Datenschutzinfo-Symbol rendern

Im Rahmen der Unterstützung des Gesetzes über digitale Dienste (Digital Services Act, DSA) müssen Reservierungsanzeigen, die im Europäischen Wirtschaftsraum (EWR) ausgeliefert werden, ein Datenschutzinfo-Symbol und einen Link zur Google-Seite „Infos zur Anzeige“ enthalten. Wenn Sie benutzerdefinierte native Anzeigen implementieren, sind Sie für das Rendern des Datenschutzinfo-Symbols verantwortlich. Wir empfehlen, dass Sie Schritte unternehmen, um den Click Listener für das Datenschutzinfo-Symbol zu rendern und einzurichten, wenn Sie die Haupt-Anzeigen-Assets rendern.

Im folgenden Beispiel wird davon ausgegangen, dass Sie in Ihrer Ansichtshierarchie ein <ImageView />-Element definiert haben, das das Datenschutzinfo-Logo enthält.

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

In den folgenden Beispielen wird das Datenschutzinfo-Symbol gerendert und das entsprechende Klickverhalten konfiguriert.

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

Impressionen erfassen und Klicks melden

Ihre App ist dafür verantwortlich, Impressionen zu erfassen und Klickereignisse an Google Mobile Ads SDK zu melden.

Impressionen erfassen

Wenn Sie eine Impression für eine benutzerdefinierte native Anzeige erfassen möchten, rufen Sie die Methode recordImpression() der Anzeige 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 melden

Wenn Sie dem SDK melden möchten, dass auf eine Asset-Ansicht geklickt wurde, rufen Sie die Methode performClick() der Anzeige auf. Geben Sie den Namen des Assets an, auf das geklickt wurde, und verwenden Sie dabei denselben String, den Sie in der Ad Manager-Benutzeroberfläche definiert haben.

myCustomFormatAd.performClick("MainImage");

Sie müssen diese Methode nicht für jede Ansicht aufrufen, die mit Ihrer Anzeige verknüpft ist. Wenn Sie ein weiteres Feld mit dem Namen „Bildunterschrift“ haben, das angezeigt werden soll, auf das der Nutzer aber nicht klickt oder tippt, muss Ihre App performClick nicht für die Ansicht dieses Assets aufrufen.

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 den OnCustomClickListener auf, falls einer angegeben wurde.
  2. Suchen Sie für jede Deep-Link-URL der Anzeige nach einem Content Resolver und starten Sie den ersten, der aufgelöst wird.
  3. Öffnen Sie einen Browser und rufen Sie die Ziel-URL der Anzeige auf.

Wenn Sie eine benutzerdefinierte Klickaktion implementieren möchten, geben Sie einen OnCustomClickListener an:

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

Zuerst mag es seltsam erscheinen, dass es benutzerdefinierte Klick-Listener gibt. Schließlich hat Ihre App dem SDK gerade mitgeteilt, dass ein Klick erfolgt ist. Warum sollte das SDK das der App dann noch einmal melden?

Dieser Informationsfluss ist aus mehreren Gründen nützlich. Vor allem ermöglicht er es dem SDK, die Reaktion auf den Klick zu steuern. Es kann beispielsweise automatisch Tracking-URLs von Drittanbietern pingen, die für das Creative festgelegt wurden, und andere Aufgaben im Hintergrund ausführen, ohne dass zusätzlicher Code erforderlich ist.