Follow

Advanced Usage - Integrating Native Ads

View original article on our GitHub

Initializing and Loading a StartAppNativeAd Object

In your Activity, create a member variable, as follows:

private StartAppNativeAd startAppNativeAd = new StartAppNativeAd(this);

To load your native ad, call the loadAd() method with a NativeAdPreferences object:

startAppNativeAd.loadAd(new NativeAdPreferences());

NativeAdPreferences can be used to customize some of the native ad properties to suit your needs, such as the number of ads to load, the image size of the ad, or whether the image should be pre-cached or not. For a full description of the NativeAdPreferences, please refer toNativeAdPreferences API.

NOTE: By default, StartAppNativeAd retrieves the image URL of the ad. The SDK is also capable of auto-loading the image as a BITMAP object. This feature is turned off by default. For enabling it, set autoBitmapDownload in NativeAdPreferences to true (please refer to Ad's image configuration).

You can register your startAppNativeAd object for callbacks by passing an AdEventListenerobject to the loadAd() method:

startAppNativeAd.loadAd(new NativeAdPreferences(), new AdEventListener() {
      @Override
      public void onReceiveAd(Ad arg0) {
            // Native Ad Received
      }

      @Override
      public void onFailedToReceiveAd(Ad arg0) {
            // Native Ad failed to receive
      }
});

Using the Native Ad Object

After initializing and loading your startAppNativeAd object, use the getNativeAds() method to obtain an array of NativeAdDetails objects for all returning ads. The NativeAdDetails object provides access to each ad's details, such as the ad's title, description, image, etc. This object also provides methods for firing an impression once the ad is displayed, and for executing the user's click on the ad. For a full description of the NativeAdDetails object, please refer toNativeAdDetails API.

Example: the following is an example of how to load 3 native ads with a pre-cached images of 150x150 pixels size, and logging their details once ready (using callbacks)

// Declare Native Ad Preferences
NativeAdPreferences nativePrefs = new NativeAdPreferences()
                                          .setAdsNumber(3)                // Load 3 Native Ads
                                          .setAutoBitmapDownload(true)    // Retrieve Images object
                                          .setPrimaryImageSize(2);        // 150x150 image

// Declare Ad Callbacks Listener
AdEventListener adListener = new AdEventListener() {     // Callback Listener
      @Override
      public void onReceiveAd(Ad arg0) {              
            // Native Ad received
            ArrayList<NativeAdDetails> ads = startAppNativeAd.getNativeAds();    // get NativeAds list

            // Print all ads details to log
            Iterator<NativeAdDetails> iterator = ads.iterator();
            while(iterator.hasNext()){
                  Log.d("MyApplication", iterator.next().toString());
            }
      }

      @Override
      public void onFailedToReceiveAd(Ad arg0) {
            // Native Ad failed to receive
            Log.e("MyApplication", "Error while loading Ad");
      }
};

// Load Native Ads
startAppNativeAd.loadAd(nativePrefs, adListener);

Note: It is possible to get less ads than you requested. It is also possible that no ad will be returned. In this case you will receive an empty array.

Showing and Clicking a Native Ad

  • Once you decide to actually show a native ad, you must call theNativeAdDetails.sendImpression() method.
  • Once the user clicks on the ad, you must call NativeAdDetails.sendClick() method.

NativeAdPreferences API:

► Set the number of Native ads to retrieve

public NativeAdPreferences setAdsNumber(int adsNumber)

set number of native ads to be received from the server.

Parameters

adsNumber - integer of the ads number

Return Value

NatvieAdPreferences – current object

► Ad's image configuration

public NativeAdPreferences setAutoBitmapDownload(boolean autoBitmapDownload)

You can choose between two options to obtain the ad's image:

  1. get the image pre-cached as a BITMAP.
  2. get the image URL only.
Parameters

autoBitmapDownload - Boolean:

  • true – native ad object will be loaded automatically with bitmap object
  • false – native ad wont load the image automatically
Return Value

NatvieAdPreferences – current object

► Set Ad's image size

public NativeAdPreferences setPrimaryImageSize(int imageSize)

Set the image size of the ad to be retrieved.

Parameters

imageSize - imageSize can get the following values:

  • 0 – for image size 72px X 72px
  • 1 – for image size 100px X 100px
  • 2 – for image size 150px X 150px
  • 3 – for image size 340px X 340px
  • 4 – for image size 1200px X 628px
Return Value

NatvieAdPreferences – current object

► Set Ad's secondary icon size

public NativeAdPreferences setSecondaryImageSize(int imageSize)

Set a secondary icon size of the ad to be retrieved.

Parameters

imageSize - imageSize can get the following values:

  • 0 – for image size 72px X 72px
  • 1 – for image size 100px X 100px
  • 2 – for image size 150px X 150px
  • 3 – for image size 340px X 340px
  • 4 – for image size 1200px X 628px
Return Value

NatvieAdPreferences – current object

NativeAdDetails API:

► Get the Ad's title

public String getTitle()

Return Value: String
► Get the Ad's description

public String getDescription()

Return Value: String
► Get the Ad's rating

public String getRating()

Get the rating of the ad in the Google Play store. The rating range is 1-5.

Return Value: Float
► Get the Ad's image URL

public String getImageUrl()

Get the image URL of the ad, according to the selected size.

Return Value: String
► Get the Ad's image bitmap

public Bitmap getImageBitmap()

Get the image of the ad as a pre-cached bitmap, if requested using the NativeAdPreferences.setAutoBitmapDownload() method.

Return Value: Bitmap
► Get the Ad's secondary icon URL

public String getSecondaryImageUrl()

Get the secondary icon URL of the ad, according to the selected size.

Return Value: String
► Get the Ad's secondary icon bitmap

public Bitmap getSecondaryImageBitmap()

Get the secondary icon of the ad as a pre-cached bitmap, if requested using the NativeAdPreferences.setAutoBitmapDownload() method.

Return Value: Bitmap
► Get the Ad's installs numbers

public String getInstalls()

Get the amount of installs in Google Play store.

Return Value: String
► Get the Ad's category

public String getCategory()

Get the category of the ad in the Google Play store.

Return Value: String
► Get the Ad's package name

public String getPackacgeName()

Get the ad's package name in the Google Play store (for example, "com.startapp.quicksearchbox").

Return Value: String
► To be called when you actually show the ad

public void sendImpression(Context context)

Call this method when you show the ad in your application.

Parameters

context – the context of the host activity

► To be called when the user clicks on the ad

public void sendClick(Context context)

Call this method when the user clicks on the ad.

Parameters

context – the context of the host activity

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

  • Avatar
    Satish Singh

    how to handle device orientation change, i.e., do i need to send impression again when ad is displayed after orientaion change.