1. Start.io
  2. SDK documentation
  3. Android

Advanced Usage

This section describes advanced usage and personal customization options and is not mandatory for the integration.

Interstitial Ads

Implement interstitial ads with objects for gaining more control over your ads, like using callbacks or using multiple ads with different properties.

To initialize an interstitial ad object, create a member variable in your activity as follows:

Java Kotlin
private StartAppAd startAppAd = new StartAppAd(this);

You can now use this object to perform the following operations:

Showing Exit Ads

To show an ad upon exiting your application when pressing the 'Back' button, override the onBackPressed() method and add the method startAppAd.onBackPressed() BEFORE the method super.onBackPressed():

Java Kotlin
@Override
public void onBackPressed() {
    startAppAd.onBackPressed();
    super.onBackPressed();
}

 

Showing Interstitials

Call showAd() in the appropriate place(s) in the activity where you would like to show the Ad:

Java Kotlin
startAppAd.showAd(); 
// Called when you want to show the ad

The following is an example of showing an Interstitial Ad between Activities:

Java Kotlin
public void btnOpenActivity (View view){
    Intent nextActivity = new Intent(this, NextActivity.class);
    startActivity(nextActivity);
    startAppAd.showAd();
}

 

Selecting Interstitial Ad Type

We highly recommend using our Automatic mode, which automatically selects the best Interstitial Ad to display, meaning the type of Ads that will generate the most revenue for you.
To add an automatic Interstitial Ad, please refer to Interstitial Ads. If you do not wish to use the automatic mode, startAppAd.loadAd() can be directed to load specific Ads to be shown later using the AdMode parameter. The options for the AdMode parameter are:

Parameter Name Description Specific Ad Load Example
AUTOMATIC (Recommended) Auto-selection of the best next Interstitial Ad to display, meaning the type of Ads that will generate the most revenue for you. The ad type can be Display or Video. This is the default startAppAd.loadAd(AdMode.AUTOMATIC)
VIDEO Use this parameter when you're interested in getting Video ads only startAppAd.loadAd(AdMode.VIDEO)
OFFERWALL Auto-selection of a Standard 2D full screen Offer Wall or a 3D Offer Wall startAppAd.loadAd(AdMode.OFFERWALL)

When using this mode, the following additional methods must be implemented in the Activity’s life-cycle:

1. Override the onSaveInstanceState(Bundle outState) method and add a call to startAppAd.onSaveInstanceState(outstate).

NOTE: Add this method immediately after the super.onSaveInstanceState(outState) method.

Example:

Java Kotlin
@Override
protected void onSaveInstanceState (Bundle outState){
   super.onSaveInstanceState(outState);
   startAppAd.onSaveInstanceState(outState);
}

2. Override the onRestoreInstanceState(Bundle savedInstanceState) method and add a call to startAppAd.onRestoreInstanceState(savedInstanceState).

NOTE: Add this method immediately before the super.onRestoreInstanceState(savedInstanceState) method.

Example:

Java Kotlin
@Override
protected void onRestoreInstanceState (Bundle savedInstanceState){
   startAppAd.onRestoreInstanceState(savedInstanceState);
   super.onRestoreInstanceState(savedInstanceState);
}

 

Explicitly Closing an Interstitial Ad

You can explicitly close an interstitial Ad by calling startAppAd.close(). This closes the Ad and returns control to the calling Activity. You can use this when implementing a timeout for an Ad.

NOTE:

Keep in mind that the user can close the Ad before timeout expires

 

Adding Interstitial Callbacks

Adding a Callback when an Interstitial Ad is loaded

startAppAd.loadAd() can be called before showing the ad, and get an implementation of AdEventListener as a parameter. To get a callback when an Ad is loaded, pass the object that implements AdEventListener (this may be your Activity) as a parameter to the loadAd method. This object must implement the following methods:

@Override
public void onReceiveAd(Ad ad) {
}
@Override
public void onFailedToReceiveAd(Ad ad) {
}

Example:

Java Kotlin
startAppAd.loadAd (new AdEventListener() {
    @Override
    public void onReceiveAd(Ad ad) {
    }
    @Override
    public void onFailedToReceiveAd(Ad ad) {
    }
});
IMPORTANT:

Do not call loadAd() from within onFailedToReceiveAd(). The SDK will automatically try to reload an ad upon a failure.

Adding a Callback when an Interstitial Ad is shown

startAppAd.showAd() can get a parameter implementation of AdDisplayListener. To get a callback when an Ad is shown, pass the object that implements AdDisplayListener (this may be your Activity) as a parameter of the method. This object must implement the following methods:


@Override
public void adHidden(Ad ad) {
	//Called when the ad has been Closed.
}

@Override
public void adDisplayed(Ad ad) {
	//Called when the ad has been rendered.
}

@Override
public void adClicked(Ad ad) {
}

@Override
public void adNotDisplayed(Ad ad) {
	//Called when the ad failed to render.
}

Example:

Java Kotlin
startAppAd.showAd(new AdDisplayListener() {
    @Override
    public void adHidden(Ad ad) {
    }
    @Override
    public void adDisplayed(Ad ad) {
    }
    @Override
    public void adClicked(Ad ad) {
    }
    @Override
    public void adNotDisplayed(Ad ad) {
    }
});

 

Banner Ads

Loading a Banner

You can load a banner without attaching it to a view, enabling you to attach it when available in a later stage.

Java Kotlin
banner.loadAd(adWidthDP, adHeightDP);

Adding Banner Callbacks

If you implemented the banner programmatically, simply pass an implementation of a BannerListener to the banner's constructor:

Java Kotlin
htmlBanner = new Banner(this, new BannerListener() {
    @Override
    public void onReceiveAd(View view) {
        // called when HTML data was received via network
    }

    @Override
    public void onFailedToReceiveAd(View view) {
        // called if no ads are available or some network error has happened
    }

    @Override
    public void onImpression(View view) {
        // called when viewable impression by IAB rules have been generated
    }

    @Override
    public void onClick(View view) {
        // called when a user clicked the banner
    }
});
 
IMPORTANT:

Do not call loadAd() from within onFailedToReceiveAd(). The SDK will automatically try to reload an ad upon a failure.

 

Adding a banner programmatically

You can add a banner programmatically, instead of using the layout XML.

For example, this is a basic example of adding a center-aligned banner to the bottom of the layout:

Java Kotlin
// Get the Main relative layout of the entire activity
RelativeLayout mainLayout = (RelativeLayout) findViewById(R.id.mainLayout);
// Define StartApp Banner
Banner startAppBanner = new Banner(context);
RelativeLayout.LayoutParams bannerParameters =
  new RelativeLayout.LayoutParams(
    RelativeLayout.LayoutParams.WRAP_CONTENT,
    RelativeLayout.LayoutParams.WRAP_CONTENT);
bannerParameters.addRule(RelativeLayout.CENTER_HORIZONTAL);
bannerParameters.addRule(RelativeLayout.ALIGN_PARENT_BOTTOM);
// Add to main Layout
mainLayout.addView(startAppBanner, bannerParameters);

Hiding the Banner

In order to hide an already displayed banner, find the banner's view and use the hideBanner() method.

For example:

Java Kotlin
Banner banner = (Banner) findViewById(R.id.startAppBanner);
banner.hideBanner();

Where R.id.startAppBanner is the banner's id from the layout XML file.

In order to show the banner again, simply use the showBanner() method.

Splash Ad

Customizing Splash Screen

Start.io (Formerly StartApp) In-Ad provides two modes for displaying splash screens - Template and User-defined. The template splash screen is a pre-defined template in which you can place your own creatives, such as application name, logo and loading animation, as described below. If you want to use your own splash screen, you can provide it as a layout, using the user-defined mode.

Customizing the Template Splash Screen

In the OnCreate method of your Activity, after calling StartAppAd.init and before setContentView, call the following static function:

Java Kotlin
StartAppAd.showSplash(this, savedInstanceState, splashConfig);

Apply the following parameters:

  • this: The context (Activity)
  • savedInstanceState: The Bundle parameter passed to your onCreate(Bundle savedInstanceState) method.
  • splashConfig: Optional object that can be used to customize some of your template's properties to suit your needs, such as your application name, logo and theme (see the example below). For a full description of the SplashConfig API, please refer to Splash Config API.

Example: the following is an example of a custom template with an OCEAN theme, modified application name, logo and landscape orientation:

Java Kotlin
StartAppAd.showSplash(this, savedInstanceState,
  new SplashConfig()
  .setTheme(SplashConfig.Theme.OCEAN)
  .setAppName("Your Application Name")
  .setLogo(R.drawable.your_360x360_logo) // resource ID
  .setOrientation(SplashConfig.Orientation.LANDSCAPE)
);
NOTE:

for optimal appearance of your Splash screen on all device densities, provide a logo of 360x360px and place it in the drawable folder of your project. If this folder does not exist, then create it.


If you do not provide a logo, then Start.io (Formerly StartApp) In-App uses the default application icon (as declared in the Manifest) and stretches it to 360x360px.

Adding a User-Defined Splash Screen

Use the following option if you already have a Splash screen for your application or if you want to design your own custom layout for your Splash screen.

1. Set a SplashConfig object with a specific layout resource ID.

2. Pass on the SplashConfig object to the showSplash static function.

For a full description of the SplashConfig API, please refer to Splash Config API.

Example:

Java Kotlin
StartAppAd.showSplash(this, savedInstanceState, 
     new SplashConfig()
            .setTheme(SplashConfig.Theme.USER_DEFINED)
            .setCustomScreen(R.layout.your_splash_screen_layout_id)
);

 

Splash Config API

The following describes the methods that you can use for customizing the Splash screen displayed in a Start.io (Formerly StartApp) In-App Splash screen Ad.

  • Set the Splash screen mode

    public SplashConfig setTheme(SplashConfig.Theme theme)

    Sets the Splash theme to Template mode or User-defined mode. Use one of the first five options below to specify a design theme for the Template mode. The last option sets the mode to User-Defined. You may refer to Customizing the Splash Screen for more information about Splash screen modes.

    Parameters
    SplashConfig.Theme.DEEP_BLUE (default)
    SplashConfig.Theme.SKY
    SplashConfig.Theme.ASHEN_SKY
    SplashConfig.Theme.BLAZE
    SplashConfig.Theme.GLOOMY
    SplashConfig.Theme.OCEAN
    SplashConfig.Theme.USER_DEFINED – user-defined mode

  • Set a Custom screen

    public SplashConfig setCustomScreen(int resource)

    Sets the splash layout to Custom mode. This is mandatory if you are using SplashConfig.Theme.USER_DEFINED.

    Parameters
    Layout Resource ID

  • Set the application name

    public SplashConfig setAppName(String appName)

    Sets the application name to be used in the Template mode.

    Parameters
    String (default is the application name from the manifest).

  • Set the logo

    public SplashConfig setLogo(int resource)

    Sets the logo to be displayed in the Template mode.

    Parameters
    Drawable resource ID (default is the icon resource from the manifest).

  • Set the orientation

    public SplashConfig setOrientation(SplashConfig.Orientation orientation)

    Sets the orientation to be used in the Template or User-defined mode.

    Parameters
    SplashConfig.Orientation.PORTRAIT (default)
    SplashConfig.Orientation.LANDSCAPE
    SplashConfig.Orientation.AUTO (use the device's orientation upon entering the application)

 

Native Ads

Initializing and Loading a Start.io NativeAd 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 to Native Ad Preferences API.

NOTE:

By default, Start.io (Formerly StartApp) NativeAd 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 Start.io NativeAd object for callbacks by passing an AdEventListener object to the loadAd() method:  

Java Kotlin
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 Start.io (Formerly StartApp) NativeAd 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 to Native Ad Details 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)

Java Kotlin
// 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 ads = startAppNativeAd.getNativeAds();    // get NativeAds list
			
			// Print all ads details to log
			Iterator 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.

Tracking the Native Ad

The SDK will log the impression and handle the click automatically. Please note that you must register the ad's view with the ad object. To make all ad elements of the view clickable register it using:

Java Kotlin
nativeAds.registerViewForInteraction(yourViewForClicksInterception);

Native Ad Preferences 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
    adsNumber - integer of the ads number 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 
    Note:

    Default Value is 2

  • 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 
    Note:

    Default Value is 2

    Return Value
    NatvieAdPreferences – current object

Native Ad Details 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") in case the ad is "app install" ad.

    Return Value: String

  • Get the Ad's call to action

    public StartAppNativeAd.CampaignAction getCampaignAction()

    Either Launch app or open Google Play.

    Return Value: Enum

  • Get the Ad's call to action text

    public StartAppNativeAd.callToAction getCallToAction()

    Get a short text to place on the "call to action" button\area.

    Return Value: String

Child-Directed Ad Serving

In case your app target children, you can pass to Start.io (Formerly StartApp) an indication for a child user by sending the user's age. Start.io will use it for applying a child-directed ad serving in case of a child user (under the age of 16)

You can send the user age upon initialization, after providing your DevId and AppId, pass the SDKAdPreferences object with its data:

Java Kotlin
StartAppSDK.init(this, 
                 "Your App ID", 
                 new SDKAdPreferences()
                      .setAge(35));
  • setAge can take an integer.

NOTE: Apps that flagged as Designated For Kids in Start.io (Formerly StartApp)  Portal are treated automatically as child-directed for all ad requests.

Adding Ad Tags

You can add tags to your ad placements. A tag is simply a free style string identifier that can be attached to any ad. Ad Tags will help you optimize your monetization by finding the right balance between ads and the perfect ad-viewing experience for your users.

For example, if you implement couple of interstitial ads in different places in your application, you can give each of them a different tag, one of them could be "Level1Complete", the other "AfterScoresBoard", then, you can monitor which placement convert better and get more engagement from your users.

In order to add tags, you simply need to add them to the right places in your code:

Banner, Mrec, Cover

Java Kotlin
AdPreferences prefs = new AdPreferences();
prefs.setAdTag("top_banner");
Banner banner = new Banner(this, prefs);

Interstitials

Java Kotlin
AdPreferences prefs = new AdPreferences();
prefs.setAdTag("game_over");
StartAppAd startAppAd = new StartAppAd(this);
startAppAd.loadAd(prefs);

Native ads

Java Kotlin
NativeAdPreferences prefs = new NativeAdPreferences();
prefs.setAdTag("level_failed");
StartAppNativeAd startAppNativeAd = new StartAppNativeAd(this);
startAppNativeAd.loadAd(prefs);
NOTE:

Ad Tags can only be named using English letters and no more than 200 characters

After getting some traffic, you could see those tags in the portal reports automatically, without extra setup.

 

Enjoy Higher eCPM with Demographic-Targeted Ads

If you know your user's gender or age, Start.io (Formerly StartApp) can use it to serve better-targeted ads which can increase your eCPM and revenue significantly.

Upon initialization, after providing your DevId and AppId, pass the SDKAdPreferences object with its data:

Java Kotlin
StartAppSDK.init(this,  
                 "Your App ID", 
                 new SDKAdPreferences()
                      .setAge(35)
                      .setGender(Gender.FEMALE));
}
  • setAge can take an integer.
  • setGender can take one of the following values: Gender.FEMALE or Gender.MALE.
Was this article helpful?
Have more questions? submit a request