Benutzerdefinierte native Anzeigenformate verwenden

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

So laden Sie eine benutzerdefinierte native Anzeige:

  1. Fügen Sie den Typ NativeAdType.CUSTOM_NATIVE als Anzeigentyp in die NativeAdRequest ein.

  2. Legen Sie die Format-ID der benutzerdefinierten nativen Anzeige fest.

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) {}
  },
)
CustomNativeSnippets.kt

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

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 Bereich Nativ im Drop-down-Menü Auslieferung:

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, mit dem die Daten für jedes Asset abgerufen werden, 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 das Verfahren zum Anzeigen eines benutzerdefinierten nativen Anzeigenformats 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.

In diesem Beispiel wird gezeigt, wie Sie eine CustomNativeAd anzeigen:

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

CustomNativeSnippets.kt

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

CustomNativeSnippets.java

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 CustomNativeAd.getMediaContent() verwenden, um den Medieninhalt abzurufen. Rufen Sie dann setMediaContent() auf, um den Medieninhalt in Ihrer Medienansicht festzulegen. Wenn die Anzeige null-Medieninhalte hat, müssen Sie alternative Pläne erstellen, um 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:

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

CustomNativeSnippets.kt

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

CustomNativeSnippets.java

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, das 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.

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

CustomNativeSnippets.kt

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

CustomNativeSnippets.java

Impressionen erfassen und Klicks melden

Ihre App ist dafür verantwortlich, Impressionen zu erfassen und Klickereignisse an GMA Next-Gen SDK zu melden.

Impressionen erfassen

Rufen Sie die Methode recordImpression() der Anzeige auf, um eine Impression für eine benutzerdefinierte native Anzeige zu erfassen:

Kotlin

// Record an impression.
customNativeAd.recordImpression()
CustomNativeSnippets.kt

Java

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

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

Rufen Sie die Methode performClick() der Anzeige auf, um dem SDK zu melden, dass auf eine Asset-Ansicht geklickt wurde. Geben Sie den Namen des Assets an, auf das geklickt wurde, und verwenden Sie dabei dieselbe String-Variable, die Sie in der Ad Manager-Benutzeroberfläche definiert haben.

Kotlin

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

Java

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

Sie müssen diese Methode nicht für jede Ansicht aufrufen, die mit Ihrer Anzeige verknüpft ist. Wenn Sie ein anderes Feld mit dem Namen „Caption“ 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 OnCustomClickListener auf, falls angegeben.
  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:

Kotlin

customNativeAd.onCustomClickListener =
  object : OnCustomClickListener {
    override fun onCustomClick(assetName: String) {
      // Perform your custom action.
    }
  }
CustomNativeSnippets.kt

Java

customNativeAd.setOnCustomClickListener(
    new OnCustomClickListener() {
      @Override
      public void onCustomClick(@NonNull String assetName) {
        // Perform your custom action.
      }
    });
CustomNativeSnippets.java

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 erfolgt ist. Warum sollte das SDK das der App 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.