Aggiunta di inserzioni native a un'app Android

L'API Native Ad ti consente di creare un'esperienza personalizzata per le inserzioni mostrate all'interno dell'app. Usando l'API Native Ad non otterrai un'inserzione pronta per la visualizzazione, ma un gruppo di proprietà dell'inserzione, come titolo, immagine e call to action, che dovrai usare per creare una visualizzazione personalizzata nel punto in cui verrà mostrata l'inserzione.

In questa guida implementeremo il seguente posizionamento delle inserzioni native. Potrai creare un'inserzione nativa con i seguenti componenti:

Passaggi dell'inserzione nativa

Passaggio 1: richiesta di un'inserzione nativa

Passaggio 2: creazione del layout dell'inserzione nativa

Passaggio 3: compilazione del layout utilizzando i metadati dell'inserzione

Passaggio 4: utilizzo di MediaView

Passaggio 5: caricamento dell'inserzione senza cache automatica

Passaggio 1: richiesta di un'inserzione nativa

Aggiungi il codice seguente nella parte superiore della tua attività per importare l'SDK Facebook Ads:

import com.facebook.ads.*;

In seguito, istanzia un oggetto NativeAd, crea un NativeAdListener e chiama loadAd() con l'ascoltatore dell'inserzione:

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

Torneremo in seguito per aggiungere il codice al metodo onAdLoaded().

Passaggio 2: creazione del layout dell'inserzione nativa

Il passaggio successivo consiste nell'estrazione dei metadati dell'inserzione e nell'utilizzarne le relative proprietà per creare l'interfaccia utente nativa personalizzata. Puoi creare la visualizzazione personalizzata in un file .xml del layout oppure puoi aggiungere degli elementi nel codice.

Nel layout della tua attività activity_main.xml, aggiungi un contenitore per Native Ad. Il contenitore deve essere com.facebook.ads.NativeAdLayout, ovvero un wrapper della parte superiore di FrameLayout con alcune funzionalità aggiuntive che ci hanno consentito di mostrare un flusso di report delle inserzioni native nella parte superiore dell'inserzione.

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

Crea un layout personalizzato native_ad_layout.xml per l'inserzione nativa:

Di seguito è riportato un esempio di layout personalizzato per l'inserzione nativa:

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

Passaggio 3: compilazione del layout utilizzando i metadati dell'inserzione

Scenario 1: visualizza l'inserzione subito dopo che è stata caricata correttamente. Modifica il metodo precedente onAdLoaded() per recuperare le proprietà Native Ad's e visualizzarle nel modo seguente:

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

L'SDK registrerà l'impression e gestirà automaticamente il clic. Tieni presente che devi registrare la visualizzazione dell'inserzione con l'istanza NativeAd per abilitarla. Per rendere cliccabili tutti gli elementi pubblicitari della visualizzazione, registrala utilizzando:

registerViewForInteraction(View view, MediaView adMediaView, MediaView adIconView)

Quando utilizzi registerViewForInteraction con NativeAds, l'SDK controlla che la chiamata sia in esecuzione sul thread principale, per evitare race condition. Eseguiamo il nostro controllo utilizzando Preconditions.checkIsOnMainThread(). Assicurati che l'implementazione sia conforme a questo standard poiché l'app si arresterà in modo improvviso se tenti di chiamare registerViewForInteraction da un thread in background.

Scenario 2: visualizza l'inserzione alcuni secondi o minuti dopo che è stata caricata correttamente. Devi controllare se l'inserzione è stata invalidata prima della visualizzazione.

Prendi spunto dal codice seguente, ma non copiarlo nel progetto poiché è solo un esempio:

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
}

Controllo dell'area cliccabile

Per un controllo più capillare degli elementi cliccabili, usa il metodo registerViewForInteraction(View view, MediaView adMediaView, MediaView adIconView, List<View> clickableViews) per registrare una lista di visualizzazioni cliccabili. Ad esempio, se desideri rendere cliccabili solo il titolo dell'inserzione e il pulsante di call to action nell'esempio precedente, puoi scrivere così:

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

Nei casi in cui riutilizzi la visualizzazione per mostrare inserzioni diverse nel tempo, assicurati di chiamare unregisterView() prima della registrazione della stessa visualizzazione con un'istanza differente di NativeAd.

Eseguendo il codice, dovresti vedere un'inserzione nativa:

Passaggio 4: utilizzo di MediaView

Per la visualizzazione dell'immagine di copertina dell'inserzione nativa, è obbligatorio utilizzare MediaView di Audience Network di Meta, che è in grado di visualizzare risorse immagine e video. Puoi consultare le nostre linee guida di progettazione per le unità delle inserzioni video native qui.

Per impostazione predefinita, le risorse immagine e video sono tutte pre-memorizzate nella cache durante il caricamento delle inserzioni native e tale condizione consente la riproduzione di video da parte di MediaView dopo il completamento del caricamento di nativeAd.

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

Durante il caricamento delle inserzioni native, puoi specificare esplicitamente anche NativeAd.MediaCacheFlag.ALL.

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

Audience Network supporta due opzioni di cache nelle inserzioni native, come definito nell'enum NativeAd.MediaCacheFlag:

Passaggio 5: caricamento dell'inserzione senza cache automatica

• È consigliabile in tutti i casi lasciare attiva l'impostazione predefinita di memorizzazione nella cache del contenuto multimediale. Tuttavia, consentiamo di sovrascrivere l'impostazione predefinita utilizzando MediaCacheFlag.NONE nel metodo loadAd. Presta molta attenzione se decidi di sovrascrivere l'impostazione di memorizzazione nella cache del contenuto multimediale predefinita.

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

• Dopo l'invocazione corretta di onAdLoaded sull'inserzione, puoi chiamare manualmente il metodo downloadMedia per avviare il download di tutti i contenuti multimediali per l'inserzione nativa quando necessario.

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

    nativeAd.downloadMedia();
}

• Infine, puoi chiamare il metodo registerViewForInteraction e visualizzare l'inserzione al completamento del caricamento dei contenuti multimediali nella callback onMediaDownloaded.

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

Se hai caricato l'inserzione senza cache automatica e non hai chiamato manualmente downloadMedia per avviare il download, il contenuto multimediale inizierà a essere scaricato solo quando viene chiamato registerViewForInteraction. Affinché un'impression sia idonea, è necessario caricare e visualizzare tutti i contenuti multimediali.

• Consulta la guida Modello di inserzione nativa per aggiungere inserzioni native nell'app.

• Esplora i nostri esempi di codice che dimostrano come utilizzare le inserzioni native. NativeAdSample è disponibile come parte dell'SDK ed è presente nella cartella AudienceNetwork/samples. Importa il progetto nell'IDE ed eseguilo su un dispositivo o sull'emulatore.