Ajout de publicités natives à une application Android

L’API Native Ad vous permet de créer une expérience personnalisée pour les publicités que vous diffusez dans votre application. Lorsque vous utilisez l’API Native Ad, vous ne recevez pas une publicité prête à être affichée, mais une série de propriétés de cette publicité, comme un titre, une image et un appel à l’action, que vous devez utiliser pour créer une vue personnalisée dans laquelle la publicité s’affichera.

Ce guide vous indique comment placer la publicité native indiquée ci-dessous. Vous allez créer une publicité native au moyen des composants suivants :

Étapes de la publicité native

Étape 1 : Demande d’une publicité native

Étape 2 : Création de la composition de votre publicité native

Étape 3 : Remplissage de votre composition à l’aide des métadonnées de la publicité

Étape 4 : Utilisation de MediaView

Étape 5 : Chargement de la publicité sans mise en cache automatique

Étape 1 : Demande d’une publicité native

Ajoutez le code suivant en haut de votre activité pour importer le SDK Facebook Ads :

import com.facebook.ads.*;

Ensuite, instanciez un objet NativeAd, créez un élément NativeAdListener, puis appelez loadAd() à l’aide de l’auditeur de publicité :

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

Nous y reviendrons plus tard pour ajouter du code à la méthode onAdLoaded().

Étape 2 : Création de la composition de votre publicité native

Ensuite, vous devez extraire les métadonnées de la publicité et utiliser ses propriétés pour créer votre interface native sur mesure. Vous pouvez créer votre vue sur mesure au format .xml ou ajouter des éléments dans le code.

Dans la composition activity_main.xml de votre activité, ajoutez un conteneur pour votre bandeau publicitaire natif Native Ad. Le conteneur doit être un élément com.facebook.ads.NativeAdLayout, c’est-à-dire un wrapper par dessus un élément FrameLayout avec une fonctionnalité supplémentaire qui nous a permis d’ajouter un flux de rapports de publicité.

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

Créez une composition personnalisée native_ad_layout.xml pour votre publicité native :

Voici un exemple de composition personnalisée pour votre publicité native :

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

Étape 3 : Remplissage de votre composition à l’aide des métadonnées de la publicité

Scénario 1 : Affichage immédiat de la publicité dès son chargement. Modifiez la méthode onAdLoaded() ci-dessus pour récupérer les propriétés de l’élément Native Ad's et les afficher comme suit :

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

Le SDK enregistrera l’impression et gérera le clic automatiquement. Notez que vous devez enregistrer la vue de la publicité avec l’instance NativeAd pour activer cette fonctionnalité. Pour rendre cliquables tous les éléments de la publicité, enregistrez-la avec :

registerViewForInteraction(View view, MediaView adMediaView, MediaView adIconView)

Lorsque vous utilisez registerViewForInteraction avec NativeAds, le SDK vérifie que l'appel s'exécute sur le fil de discussion principal, afin d'éviter les situations de course. Nous effectuons notre vérification en utilisant Preconditions.checkIsOnMainThread(). Veillez à ce que votre implémentation soit conforme à cette norme, car votre application cessera de fonctionner si vous essayez d'appeler registerViewForInteraction depuis un fil de discussion d'arrière-plan.

Scénario 2 : Affichage de la publicité dans les secondes ou les minutes qui suivent son chargement. Avant d’afficher la publicité, assurez-vous qu’elle n’a pas été invalidée.

Suivez l’idée ci-dessous, mais ne copiez surtout pas le code dans votre projet, car il s’agit d’un exemple :

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
}

Contrôle des zones cliquables

Pour contrôler plus précisément les zones cliquables, vous pouvez utiliser l’élément registerViewForInteraction(View view, MediaView adMediaView, MediaView adIconView, List<View> clickableViews) afin d’enregistrer une liste des vues sur lesquelles il est possible de cliquer. Par exemple, si vous souhaitez uniquement que le titre de la publicité et le bouton d’appel à l’action soient cliquables dans l’exemple précédent, vous pouvez l’écrire comme suit :

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

Lorsque vous réutilisez la vue pour présenter différentes publicités au fil du temps, veillez à appeler unregisterView() avant d’enregistrer la même vue avec une autre instance de NativeAd.

Exécutez le code ; vous devriez voir une publicité native :

Étape 4 : Utilisation de MediaView

Pour afficher l'image de couverture de la publicité native, il est obligatoire d'utiliser le Meta Audience Network MediaView qui peut afficher à la fois des images et des vidéos. Vous pouvez consulter nos directives de conception pour les publicités vidéo natives ici.

Par défaut, les images et vidéos sont toutes mises en cache au préalable lors du chargement des publicités natives, ce qui permet à MediaView de lire les vidéos immédiatement après la fin du chargement de nativeAd.

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

En outre, vous pouvez spécifier explicitement NativeAd.MediaCacheFlag.ALL lors du chargement des publicités natives.

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

Audience Network prend en charge deux options de cache dans les publicités natives, telles que définies dans l'enum NativeAd.MediaCacheFlag :

Étape 5 : Chargement de la publicité sans mise en cache automatique

• Nous vous déconseillons de désactiver le cache multimédia par défaut. Cependant, nous vous permettons de remplacer la valeur par défaut en utilisant MediaCacheFlag.NONE dans la méthode loadAd. Veuillez faire preuve de prudence si vous décidez de remplacer notre mise en cache par défaut des contenus multimédia.

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

• Une fois onAdLoaded invoqué avec succès sur votre publicité, vous pouvez appeler manuellement la méthode downloadMedia pour commencer à télécharger tous les contenus multimédia pour la publicité native, le cas échéant.

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

    nativeAd.downloadMedia();
}

• Enfin, vous pouvez appeler la méthode registerViewForInteraction et afficher la publicité lorsque le contenu multimédia a fini de se charger dans le rappel 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
}

Si vous avez chargé la publicité sans cache automatique et n'avez pas appelé manuellement downloadMedia pour lancer le téléchargement, le contenu multimédia ne commencera à être téléchargé que lorsque registerViewForInteraction sera appelé. Tous les contenus multimédia doivent être chargés et affichés pour une impression admissible.

• Pour ajouter des publicités natives à votre application, consultez le guide des modèles de publicités natives.

• Découvrez nos exemples de code qui montrent le fonctionnement des publicités natives. L’exemple NativeAdSample fait partie du SDK et se situe dans le dossier AudienceNetwork/samples. Importez le projet dans votre environnement de développement intégré, et lancez-le sur un appareil ou sur le simulateur.