Facebook Audience Network Android SDK 4.99 Upgrade Guide

What's New?

  1. We added NativeBannerAd and AdIconView in the Android SDK 4.99 release. NativeBannerAd is used for showing a native ad without the ad image or video. In a native banner ad, ad icon, ad title, ad CTA button, and ad choices icon are still required to be shown to users.

    If using NativeBannerAd, you will need to select the 'Native banner' format for your placement in Monetization Manager. If you are updating from NativeAd to NativeBannerAd you may continue to use the same placement, but you will need to update the format type.





    You can refer to Audience Network Android API reference and NativeBannerAd integration guide for more details about how to use these two new interfaces.

  2. We have a new requirement for showing a native ad in the app. When requesting a NativeAd ad instance, the MediaView view instance is required to show the ad image, video or carousel content. You can check our latest native ad developer doc for more information.

  3. We added downloadMedia method in NativeAd and NativeBannerAd interfaces. This is used when calling loadAd(NativeBannerAd.MediaCacheFlag) with MediaCacheFlag.NONE. We added NativeAdListener, in which onMediaDownloaded(Ad) will be called when media content is successfully downloaded.

  4. We added following new methods in the NativeAd and NativeBannerAd interfaces:
    New Method Description

    getAdvertiserName()

    Get the name of the Facebook Page or mobile app that represents the business running each ad.

    getAdHeadline()

    Get the headline that the advertiser entered when they created their ad. This is usually the ad's main title.

    getAdLinkDescription()

    Get additional information that the advertiser may have entered.

    getAdSponsoredTranslation()

    Get the word 'sponsored', translated into the language based upon Facebook app language setting.

    getAdTranslation()

    Get the word 'ad', translated into the language based upon Facebook app language setting.

    getAdPromotedTranslation()

    Get the word 'promoted', translated into the language based upon Facebook app language setting.


  5. We also added a new view interface called NativeBannerAdView which shows a native banner ad using a template. This is similar to NativeAdView interface except it does not show ad image, video or carousel content. There are two different height options HEIGHT_100 and HEIGHT_120 in NativeBannerAdView.Type.

    NativeBannerAdView.Type

    HEIGHT_100

    HEIGHT_120


    You can refer to Audience Network Android API reference and Native Ads Template guide for more details about how to use these two new interfaces.

  6. isAdInvalidated() method is added into Ad interface and applies to all types of ads, which is used to check whether the ad has already Expired before showing ad.

What has changed?

In this new release, we have a few APIs has been changed for better ad quality.

  1. setNativeAd(NativeAd) from MediaView interface is not public any longer.

  2. setNativeAd(NativeAd) and unsetNativeAd() from MediaViewVideoRenderer interface are not public any longer.

  3. ICON, IMAGE and VIDEO are removed from MediaCacheFlag enum, and MediaCacheFlag enum is moved to NativeAdBase, which supports only two cache options in native ads and native banner ads:

    Cache Constants Description

    NONE

    No pre-caching

    ALL

    Pre-cache all (icon, images, and video), default

  4. NativeAd interface changes:
    • registerViewForInteraction(View) is replaced by registerViewForInteraction(View, MediaView, AdIconView) where AdIconView is optional.
    • registerViewForInteraction(View, List<View>) is replaced by registerViewForInteraction(View, MediaView, AdIconView, List<View>) where AdIconView is optional.
  5. We renamed the following methods in the NativeAd interface:

    Previous Method name Current Method name

    getAdBody()

    getAdBodyText()

    getAdRawBody()

    getAdUntrimmedBodyText()

What has been removed?

In this new release, we have removed some APIs for better ad quality.

  1. setAutoPlay(boolean) is removed from MediaView interface.

  2. disableAutoRefresh() is removed from AdView interface and auto refresh for banner ads is no longer supported.

  3. HEIGHT_100 and HEIGHT_120 are removed from NativeAdView.Type enum.

  4. NativeAd interface removal:
    • setMediaViewAutoplay(boolean) is removed.
    • NativeAd::downloadAndDisplayImage(NativeAd.Image, ImageView) is removed.
    • NativeAd.Image is moved to NativeAdBase.Image, and NativeAdBase.Image::getUrl() is removed.
  5. We removed the following methods in the NativeAd interface:

    Removed Methods

    getAdTitle()

    getAdSubtitle()

Migration Steps

Remove the older version of Audience Network Android SDK from your Android Studio project and replace with the latest one downloaded from the change log. Or increase the version number to 4.99.0 in module-level build.gradle. Follow the 4 use cases below about how your app shows native ads.

Apps using MediaCacheFlag enum when calling loadAd(MediaCacheFlag)

Code to load native ad before:

private  NativeAd nativeAd;
// Create a native ad request with a unique placement ID 
nativeAd = new NativeAd(getActivity(), "YOUR_PLACEMENT_ID");
...
// Initiate a request to load an ad.
nativeAd.loadAd(NativeAd.MediaCacheFlag.ICON);

Code to load native ad using Android 4.99 release:

private  NativeAd nativeAd;
// Create a native ad request with a unique placement ID 
nativeAd = new NativeAd(getActivity(), "YOUR_PLACEMENT_ID");
...
// Initiate a request to load an ad.
nativeAd.loadAd();

Apps using NativeAd and MediaView to show ad media

  1. If you app shows native ads and uses MediaView interface to show ad image, video or carousel content, remove all references that call setNativeAd method from MediaView instance. You need to register MediaView instance to NativeAd instance with the following:

    Replace registerViewForInteraction(View) with registerViewForInteraction(View, MediaView).
    Or replace registerViewForInteraction(View, List<View>) with registerViewForInteraction(View, MediaView, List<View>).

  2. Code to show native ads before:
    // Instantiate MediaView from its Parent View
    MediaView nativeAdMedia = (MediaView)adView.findViewById(R.id.native_ad_media);
    // Need to remove setNativeAd as it's not supported in 4.99 release
    nativeAdMedia.setNativeAd(nativeAd);
    ...
    // Need to replace with new interface as it's not supported in 4.99 release
    nativeAd.registerViewForInteraction(
            adView,
            Arrays.asList(nativeAdCallToAction, nativeAdMedia));
    Code to show native ads using Android 4.99 release:
    // Instantiate MediaView from its Parent View
    MediaView nativeAdMedia = (MediaView)adView.findViewById(R.id.native_ad_media);
    ...
    // Register MediaView object with NativeAd object
    nativeAd.registerViewForInteraction(
            adView,
            nativeAdMedia,
            Arrays.asList(nativeAdCallToAction, nativeAdMedia));
  3. If your app shows ad icon, you need to remove all references that call NativeAd::downloadAndDisplayImage(NativeAd.Image, ImageView) because it is no longer supported. To show ad icon, you need to create a view instance with AdIconView type and calls registerViewForInteraction(View, MediaView, AdIconView, List<View>) method.

    Code to show ad icon before:
    // Instantiate UIImageView from its Parent View
    ImageView nativAdIconView = adView.findViewById(R.id.native_ad_icon);
    ...
    // Load ad icon image; Need to remove as it's not supported in 4.99 release
    NativeAd.Image adIcon = nativeAd.getAdIcon();
    NativeAd.downloadAndDisplayImage(adIcon, nativAdIconView)
    Code to show ad icon using Android 4.99 release:
    // Instantiate AdIconView from its Parent View
    AdIconView nativAdIconView = (AdIconView) adView.findViewById(R.id.native_ad_icon);
    ...
    // Register AdIconView object with NativeAd object
    nativeAd.registerViewForInteraction(
            adView,
            nativeAdMedia,
            nativAdIconView,
            Arrays.asList(nativeAdCallToAction, nativeAdMedia));

Apps using NativeAd and NativeAd.Image to load and show ad image

  1. NativeAd::downloadAndDisplayImage(NativeAd.Image, ImageView) is removed from NativeAd in the latest release. Remove all NativeAd::downloadAndDisplayImage function calls.

  2. If your app uses ImageView equivalent views to show ad image, you need to replace them with MediaView for adCoverImage, AdIconView for adIcon and follow the steps described in the above scenario.

Apps showing native ads excluding ad media

  1. At minimum to show native ads, your app needs to include ad title, CTA button, advertiser icon, and ad choices icon. Refer to Implementation Requirements for Audience Network Ads for more details.

  2. If your app does not show advertiser assets including image, video or carousel content, you can use NativeBannerAd and AdIconView to show native ads with the banner equivalent format.

    You can refer to Audience Network Android API reference and NativeBannerAd integration guide for more details about how to use these two new interfaces.

Apps using NativeAdView to show native ad template

If your app shows native ad template using NativeAdView, HEIGHT_100 and HEIGHT_120 are not supported by NativeAdView.Type from this new release.


You can refer to Native Ads Template for more details about how to show native template ad with 100 and 120 height options using NativeBannerAdView