Native Werbeanzeigen zu einer Android-App hinzufügen

Mit der Native Ad API kannst du die Werbeanzeigen, die du in deiner App anzeigen möchtest, nach deinen Wünschen anpassen. Du erhältst über die Native Ad API keine fertigen Werbeanzeigen, sondern eine Gruppe an Werbeanzeigeneigenschaften, wie einen Titel, ein Bild und einen Call to Action, und kannst dir daraus eine Werbeanzeige individuell zusammenstellen.

In diesem Leitfaden implementieren wir die folgende Native Ad-Platzierung. Du erstellst eine native Werbeanzeige, die die folgenden Komponenten enthält:

Schritte zur Erstellung von nativen Werbeanzeigen

Schritt 1: Eine native Werbeanzeige anfordern

Schritt 2: Das Layout deiner nativen Werbeanzeige erstellen

Schritt 3: Die Metadaten der Werbeanzeige in dein Layout einfügen

Schritt 4: MediaView verwenden

Schritt 5: Werbeanzeige ohne automatisches Caching laden

Schritt 1: Eine native Werbeanzeige anfordern

Füge folgenden Code am Anfang deiner Aktivität ein, um das Facebook-Werbeanzeigen-SDK zu importieren:

import com.facebook.ads.*;

Instanziiere dann ein NativeAd-Objekt, erstelle einen NativeAdListener und rufe loadAd(...) mit dem Werbeanzeigen-Listener auf:

private final String TAG = "NativeAdActivity".getClass().getSimpleName();
private NativeAd nativeAd;

private void loadNativeAd() {
    // Instantiate a NativeAd object.
    // NOTE: the placement ID will eventually identify this as your App, you can ignore it for
    // now, while you are testing and replace it later when you have signed up.
    // While you are using this temporary code you will only get test ads and if you release
    // your code like this to the Google Play your users will not receive ads (you will get a no fill error).
    nativeAd = new NativeAd(this, "YOUR_PLACEMENT_ID");

    NativeAdListener nativeAdListener = new NativeAdListener() {
        @Override
        public void onMediaDownloaded(Ad ad) {
            // Native ad finished downloading all assets
            Log.e(TAG, "Native ad finished downloading all assets.");
        }

        @Override
        public void onError(Ad ad, AdError adError) {
        // Native ad failed to load
            Log.e(TAG, "Native ad failed to load: " + adError.getErrorMessage());
        }

        @Override
        public void onAdLoaded(Ad ad) {
            // Native ad is loaded and ready to be displayed
            Log.d(TAG, "Native ad is loaded and ready to be displayed!");
        }

        @Override
        public void onAdClicked(Ad ad) {
            // Native ad clicked
            Log.d(TAG, "Native ad clicked!");
        }

        @Override
        public void onLoggingImpression(Ad ad) {
            // Native ad impression
            Log.d(TAG, "Native ad impression logged!");
        }
    };

    // Request an ad
    nativeAd.loadAd(
            nativeAd.buildLoadAdConfig()
                    .withAdListener(nativeAdListener)
                    .build());
}

Später kommen wir hierher zurück, um Code zur onAdLoaded()-Methode hinzuzufügen.

Schritt 2: Das Layout deiner nativen Werbeanzeige erstellen

Als Nächstes musst du die Metadaten der Werbeanzeige extrahieren und aus ihren Eigenschaften eine individuelle native Benutzeroberfläche erstellen. Du kannst deine individuelle Ansicht in einer Layout-XML-Datei erstellen oder Elemente als Code hinzufügen.

Füge im Layout deiner Aktivität activity_main.xml einen Container für deine Native Ad hinzu. Der Container muss ein com.facebook.ads.NativeAdLayout sein, wobei es sich um einen Wrapper für ein FrameLayout mit einigen Zusatzfunktionen handelt, mit dem wir einen nativen Anzeigenberichterstattungsfluss über der Werbeanzeige darstellen können.

<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:gravity="center_horizontal"
    android:paddingTop="50dp">
    ...
    <ScrollView
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:paddingBottom="50dp">

        <com.facebook.ads.NativeAdLayout
             android:id="@+id/native_ad_container"
             android:layout_width="match_parent"
             android:layout_height="wrap_content"
             android:orientation="vertical" />
     </ScrollView>
    ...
</RelativeLayout>

Erstellung eines individuellen Layouts native_ad_layout.xml für deine native Werbeanzeige:

Unten findest du ein Beispiel für ein individuelles Layout für deine native Werbeanzeige:

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/ad_unit"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:background="@android:color/white"
    android:orientation="vertical"
    android:paddingLeft="10dp"
    android:paddingRight="10dp">

    <LinearLayout
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:orientation="horizontal"
        android:paddingBottom="10dp"
        android:paddingTop="10dp">

        <com.facebook.ads.MediaView
            android:id="@+id/native_ad_icon"
            android:layout_width="35dp"
            android:layout_height="35dp" />

        <LinearLayout
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:orientation="vertical"
            android:paddingLeft="5dp"
            android:paddingRight="5dp">

        <TextView
            android:id="@+id/native_ad_title"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:ellipsize="end"
            android:lines="1"
            android:textColor="@android:color/black"
            android:textSize="15sp" />

        <TextView
            android:id="@+id/native_ad_sponsored_label"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:ellipsize="end"
            android:lines="1"
            android:textColor="@android:color/darker_gray"
            android:textSize="12sp" />

    </LinearLayout>

    <LinearLayout
        android:id="@+id/ad_choices_container"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:gravity="end"
        android:orientation="horizontal" />

    </LinearLayout>

    <com.facebook.ads.MediaView
        android:id="@+id/native_ad_media"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:gravity="center" />

    <LinearLayout
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:orientation="horizontal"
        android:padding="5dp">

        <LinearLayout
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:layout_weight="3"
            android:orientation="vertical">

            <TextView
                android:id="@+id/native_ad_social_context"
                android:layout_width="match_parent"
                android:layout_height="wrap_content"
                android:ellipsize="end"
                android:lines="1"
                android:textColor="@android:color/darker_gray"
                android:textSize="12sp" />

            <TextView
                android:id="@+id/native_ad_body"
                android:layout_width="match_parent"
                android:layout_height="wrap_content"
                android:ellipsize="end"
                android:gravity="center_vertical"
                android:lines="2"
                android:textColor="@android:color/black"
                android:textSize="12sp" />

        </LinearLayout>

        <Button
            android:id="@+id/native_ad_call_to_action"
            android:layout_width="100dp"
            android:layout_height="30dp"
            android:layout_gravity="center_vertical"
            android:layout_weight="1"
            android:background="#4286F4"
            android:paddingLeft="3dp"
            android:paddingRight="3dp"
            android:textColor="@android:color/white"
            android:textSize="12sp"
            android:visibility="gone" />

    </LinearLayout>

</LinearLayout>

Schritt 3: Die Metadaten der Werbeanzeige in dein Layout einfügen

Szenario 1: Die Werbeanzeige soll nach dem erfolgreichen Laden sofort angezeigt werden. Passe die oben angegebene onAdLoaded()-Methode an, um die Eigenschaften der Native Ad's abzurufen und sie anzuzeigen:

private NativeAdLayout nativeAdLayout;
private LinearLayout adView;
private NativeAd nativeAd;

private void loadNativeAd() {
    // Instantiate a NativeAd object. 
    // NOTE: the placement ID will eventually identify this as your App, you can ignore it for
    // now, while you are testing and replace it later when you have signed up.
    // While you are using this temporary code you will only get test ads and if you release
    // your code like this to the Google Play your users will not receive ads (you will get a no fill error).
    nativeAd = new NativeAd(this, "YOUR_PLACEMENT_ID");

    NativeAdListener nativeAdListener = new NativeAdListener() {
        ...
        @Override
        public void onAdLoaded(Ad ad) {
            // Race condition, load() called again before last ad was displayed
            if (nativeAd == null || nativeAd != ad) {
                return;
            }
            // Inflate Native Ad into Container
            inflateAd(nativeAd);
        }
        ...
    };

    // Request an ad
    nativeAd.loadAd(
            nativeAd.buildLoadAdConfig()
                    .withAdListener(nativeAdListener)
                    .build());
}

private void inflateAd(NativeAd nativeAd) {

    nativeAd.unregisterView();

    // Add the Ad view into the ad container.
    nativeAdLayout = findViewById(R.id.native_ad_container);
    LayoutInflater inflater = LayoutInflater.from(NativeAdActivity.this);
    // Inflate the Ad view.  The layout referenced should be the one you created in the last step.
    adView = (LinearLayout) inflater.inflate(R.layout.native_ad_layout_1, nativeAdLayout, false);
    nativeAdLayout.addView(adView);

    // Add the AdOptionsView
    LinearLayout adChoicesContainer = findViewById(R.id.ad_choices_container);
    AdOptionsView adOptionsView = new AdOptionsView(NativeAdActivity.this, nativeAd, nativeAdLayout);
    adChoicesContainer.removeAllViews();
    adChoicesContainer.addView(adOptionsView, 0);

    // Create native UI using the ad metadata.
    MediaView nativeAdIcon = adView.findViewById(R.id.native_ad_icon);
    TextView nativeAdTitle = adView.findViewById(R.id.native_ad_title);
    MediaView nativeAdMedia = adView.findViewById(R.id.native_ad_media);
    TextView nativeAdSocialContext = adView.findViewById(R.id.native_ad_social_context);
    TextView nativeAdBody = adView.findViewById(R.id.native_ad_body);
    TextView sponsoredLabel = adView.findViewById(R.id.native_ad_sponsored_label);
    Button nativeAdCallToAction = adView.findViewById(R.id.native_ad_call_to_action);

    // Set the Text.
    nativeAdTitle.setText(nativeAd.getAdvertiserName());
    nativeAdBody.setText(nativeAd.getAdBodyText());
    nativeAdSocialContext.setText(nativeAd.getAdSocialContext());
    nativeAdCallToAction.setVisibility(nativeAd.hasCallToAction() ? View.VISIBLE : View.INVISIBLE);
    nativeAdCallToAction.setText(nativeAd.getAdCallToAction());
    sponsoredLabel.setText(nativeAd.getSponsoredTranslation());

    // Create a list of clickable views
    List<View> clickableViews = new ArrayList<>();
    clickableViews.add(nativeAdTitle);
    clickableViews.add(nativeAdCallToAction);

    // Register the Title and CTA button to listen for clicks.
    nativeAd.registerViewForInteraction(
            adView, nativeAdMedia, nativeAdIcon, clickableViews);
}

Das SDK protokolliert die Impression und verarbeitet den Klick automatisch. Beachte, dass du die Ansicht der Werbeanzeige bei der NativeAd-Instanz registrieren musst, um dies zu ermöglichen. Damit alle Anzeigenelemente der Ansicht klickbar sind, registriere sie wie folgt:

registerViewForInteraction(View view, MediaView adMediaView, MediaView adIconView)

Wird registerViewViewForInteraction mit nativen Werbeanzeigen verwendet, überprüft das SDK, ob der Aufruf auf dem Haupt-Thread läuft, um eine Wettlaufsituation zu vermeiden. Wir führen unsere Prüfung mithilfe von Preconditions.checkIsOnMainThread() durch. Bitte stelle sicher, dass deine Implementierung diesem Standard entspricht, da deine App abstürzt, wenn du versuchst, registerViewViewForInteraction über einen Background-Thread aufzurufen.

Szenario 2: Die Werbeanzeige soll einige Sekunden oder Minuten, nachdem sie erfolgreich geladen wurde, angezeigt werden. Du solltest prüfen, ob die Werbeanzeige ungültig gemacht wurde, bevor du sie anzeigst.

Orientiere dich an nachstehendem Beispiel, aber kopiere bitte den Code nicht in dein Projekt, da es sich wie gesagt nur um ein Beispiel handelt:

private NativeAd nativeAd;

private void loadNativeAd() {
    // Instantiate a NativeAd object. 
    // NOTE: the placement ID will eventually identify this as your App, you can ignore it for
    // now, while you are testing and replace it later when you have signed up.
    // While you are using this temporary code you will only get test ads and if you release
    // your code like this to the Google Play your users will not receive ads (you will get a no fill error).
    nativeAd = new NativeAd(this, "YOUR_PLACEMENT_ID");

    NativeAdListener nativeAdListener = new NativeAdListener() {
        ...
    };

    // Request an ad
    nativeAd.loadAd(
            nativeAd.buildLoadAdConfig()
                    .withAdListener(nativeAdListener)
                    .build());

    // Here is just an example for displaying the ad with delay
    // Please call this method at appropriate timing in your project
    showNativeAdWithDelay();
}

private void showNativeAdWithDelay() {
    /**
     * Here is an example for displaying the ad with delay;
     * Please do not copy the Handler into your project
     */
    Handler handler = new Handler();
    handler.postDelayed(new Runnable() {
        public void run() {
            // Check if nativeAd has been loaded successfully
            if(nativeAd == null || !nativeAd.isAdLoaded()) {
                return;
            }
            // Check if ad is already expired or invalidated, and do not show ad if that is the case. You will not get paid to show an invalidated ad.
            if(nativeAd.isAdInvalidated()) {
                return;
            }
            inflateAd(nativeAd); // Inflate NativeAd into a container, same as in previous code examples
        }
    }, 1000 * 60 * 15); // Show the ad after 15 minutes
}

Festlegen des klickbaren Bereichs

Um den klickbaren Bereich genau festzulegen, kannst du mit registerViewForInteraction(View view, MediaView adMediaView, MediaView adIconView, List<View> clickableViews) eine Liste der klickbaren Ansichten registrieren. Wenn z. B. im vorherigen Beispiel nur der Anzeigentitel und der Call to Action-Button klickbar sein sollen, kann der Code etwa wie folgt aussehen:

@Override
public void onAdLoaded(Ad ad) {
    ...
    // Create a list of clickable views
    List<View> clickableViews = new ArrayList<>();
    clickableViews.add(nativeAdTitle);
    clickableViews.add(nativeAdCallToAction);

    // Register the Title and CTA button to listen for clicks.
    nativeAd.registerViewForInteraction(
            adView, nativeAdMedia, nativeAdIcon, clickableViews);
    ...
}

Wenn du die Ansicht wiederverwendest, um über einen bestimmten Zeitraum verschiedene Werbeanzeigen anzuzeigen, vergiss nicht, unregisterView() aufzurufen, bevor du dieselbe Ansicht bei einer anderen Instanz von NativeAd registrierst.

Führe den Code aus. Du solltest eine native Werbeanzeige sehen:

Schritt 4: MediaView verwenden

Für die Anzeige des Titelbilds der native Werbeanzeige muss Meta Audience Network MediaView verwendet werden. Damit kannst du sowohl Bild- als auch Videoelemente anzeigen. Unsere Designrichtlinien für native Video-Werbeeinheiten findest du hier.

Standardmäßig werden Bild- und Videoelemente beim Laden von nativen Werbeanzeigen im Voraus zwischengespeichert, sodass MediaView Videos unmittelbar nach dem Laden von nativeAd abspielen kann.

private void loadNativeAd() {
    ...
    nativeAd.loadAd();
}

Du kannst beim Laden von Native Ads auch explizit NativeAd.MediaCacheFlag.ALL angeben.

private void loadNativeAd() {
    ...
    nativeAd.loadAd(
            nativeAd.buildLoadAdConfig()
                    .withMediaCacheFlag(NativeAdBase.MediaCacheFlag.ALL)
                    .build());
}

Audience Network unterstützt zwei Cache-Optionen bei nativen Werbeanzeigen, wie im NativeAd.MediaCacheFlag-Enum definiert:

Schritt 5: Werbeanzeige ohne automatisches Caching laden

• Wir empfehlen unbedingt, Medien-Caching standardmäßig immer zu aktivieren. Du kannst den Standard jedoch überschreiben. Verwenden hierzu MediaCacheFlag.NONE in der loadAd-Methode. Gehe äußerst vorsichtig vor, wenn du unser Standard-Medien-Caching überschreibst.

private final String TAG = NativeAdActivity.class.getSimpleName();
private NativeAd nativeAd;

private void loadNativeAd() {
    // Instantiate a NativeAd object. 
    // NOTE: the placement ID will eventually identify this as your App, you can ignore it for
    // now, while you are testing and replace it later when you have signed up.
    // While you are using this temporary code you will only get test ads and if you release
    // your code like this to the Google Play your users will not receive ads (you will get a no fill error).
    nativeAd = new NativeAd(this, "YOUR_PLACEMENT_ID");
    NativeAdListener nativeAdListener = new NativeAdListener() {
        ...
    };

    // Request an ad without auto cache
    nativeAd.loadAd(
            nativeAd.buildLoadAdConfig()
                    .withAdListener(nativeAdListener)
                    .withMediaCacheFlag(NativeAdBase.MediaCacheFlag.NONE)
                    .build());
}

• Nachdem onAdLoaded in deiner Anzeige erfolgreich aufgerufen wurde, kannst du die downloadMedia-Methode manuell aufrufen, um mit dem Herunterladen aller Medien für die native Werbeanzeige zu beginnen, sofern notwendig.

@Override
public void onAdLoaded(Ad ad) {
    if (nativeAd == null || nativeAd != ad) {
        return;
    }

    nativeAd.downloadMedia();
}

• Abschließend kannst du die registerViewForInteraction-Methode aufrufen und die Anzeige nach Abschluss des Ladevorgangs im onMediaDownloaded-Rückruf anzeigen.

@Override
public void onMediaDownloaded(Ad ad) {
    if (nativeAd == null || nativeAd != ad) {
        return;
    }

    inflateAd(nativeAd); // Inflate NativeAd into a container, same as in previous code examples
}

Wenn du die Werbeanzeige mit automatischem Caching geladen und nicht manuell downloadMedia aufgerufen hast, um den Download zu starten, werden die Medien nur dann heruntergeladen, wenn registerViewForInteraction aufgerufen wird. Für zulässige Impressions müssen alle Medien geladen und angezeigt werden.

• Informationen zum Hinzufügen von nativen Werbeanzeigen zu deiner App findest du im Leitfaden zur Vorlage für native Werbeanzeigen.

• Sieh dir unsere Codebeispiele für die Verwendung von nativen Werbeanzeigen an. Die NativeAdSample steht als Teil des SDK zur Verfügung und befindet sich im Ordner AudienceNetwork/samples. Importiere das Projekt in deine IDE und führe es auf einem Gerät oder im Emulator aus.