Integration via Maven

SDK Version: 5.1.0

This document describes the basic procedure for integrating Start.io (Formerly StartApp) In-App Ads into your Android applications.

After this simple integration process, Start.io In-App Ads enables you to reap the benefits of Start.io's In-App monetization products, which maximize the revenue generated by your application. All this profit-making is achieved with minimal effort and minimal interference with your users' experience.

Getting Started

Step 1, Adding and Initializing the SDK to Your Project

Pull the latest version of the Start.io SDK with Maven integration.

repositories {
  mavenCentral()
}

dependencies {
  implementation 'com.startapp:inapp-sdk:5.+'
}

<uses-permission android:name="android.permission.BLUETOOTH" />

<uses-permission android:name="android.permission.AD_ID" />

<meta-data
     android:name="com.startapp.sdk.APPLICATION_ID"
     android:value="startapp_app_id" />

<meta-data
 android:name="com.startapp.sdk.RETURN_ADS_ENABLED"
 android:value="false" />

repositories {
  maven { url 'https://startappdev.bintray.com/maven' }
}

dependencies {
  implementation 'com.startapp:inapp-sdk:5.+'
}

<uses-permission android:name="android.permission.BLUETOOTH" />

<provider
 android:name="com.startapp.sdk.adsbase.StartAppInitProvider"
 android:authorities="${applicationId}.startappinitprovider"
 tools:node="remove" />

StartAppSDK.init(this, "StartApp App ID", true);

Step 2, Obfuscation (Mandatory for Proguard users)

Obfuscation protects an application from reverse-engineering or modification by making it harder for a third-party to access your source (decompiled) code.

Start.io In-Ad is already obfuscated! Therefore, if you did not obfuscate your application using ProGuard™, then you can skip this step. If you have obfuscated your application using ProGuard, then use the following in the ProGuard configuration file:

-keep class com.startapp.** {
      *;
}

-keep class com.truenet.** {
      *;
}

-keepattributes Exceptions, InnerClasses, Signature, Deprecated, SourceFile,
LineNumberTable, *Annotation*, EnclosingMethod
-dontwarn android.webkit.JavascriptInterface
-dontwarn com.startapp.**

-dontwarn org.jetbrains.annotations.**

Step 3, App Permissions (COPPA Compliant)

In case your app target children (as defined under applicable laws, such as 13 in the US and 16 in the EU) and you integrated the SDK version through Maven, you need to remove the WIFI permission from your manifest merger. In order to do so, follow these steps:

1. Add this line to the manifest element:

   xmlns:tools="http://schemas.android.com/tools"

2. Add this line to your permission list:

   <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" tools:node="remove"/>

Step 4, Google Play Families Policy Requirements 

Guidance for Apps Directed At Children

If your app is designed primarily for children (such as under 16 in the European Economic Area (EEA) or under 13 in other countries):

Google Play requires that you participate in Designed for Families Program and comply with Google Play’s Families Policy Requirements.

Guidance for Apps Directed At a Mixed Audience

If your app is designed for everyone, including children and families, then follow these steps:

1. Integrate Start.io SDK 5.0+
2. Start.io SDK 5.0+ enables publishers of mixed audience apps to flag specific end-users as children, as may be permitted or required by applicable law (e.g. COPPA, GDPR, etc.). Publishers of child-directed apps are responsible for determining whether an app is permitted to flag at the end-user level, using age gates or must treat all end-users as children. Publishers should consult with their legal counsel accordingly.
   1. The indication whether your app is directed at a mixed audience (i.e. for everyone, including children and families), should be done using a “is_mixed_audience” flag, by setting its value to “true” or “false”.
      
      For Example:
      

      <meta-data
      android:name="com.startapp.sdk.MIXED_AUDIENCE"
      android:value="true"/>

   2. The indication of whether a specific end-user is a child should be done using a “is_child_directed” flag, by setting its value to “true” or “false”.
      
      For Example:
      

      <meta-data
      android:name="com.startapp.sdk.CHILD_DIRECTED"
      android:value="true"/>

   The API should be set before initializing the SDK.

3. If you set "is_mixed_audience" flag as "true", then your app will not transmit the Advertising ID for children and end-users for unknown ages.

Regulation Advanced Settings

Start.io Consent 

We help you to be compliant with Privacy laws, when embedding our SDK.

Privacy laws require to disclose to the app users that Start.io ( Formerly StartApp) SDK is embedded in your app and collects and processes their personal data for the purpose of displaying personalized advertising. In some jurisdictions, users’ consent is required as well. We embedded a disclosure / consent box which will be presented to the app users and will enable them to review Start.io Privacy Policy, as well as exercise their rights.

Start.io disclosure/ consent box is presented immediately after the application is launched. Start.io disclosure/ consent box is enabled by default. 

Consent From European Users (GDPR) 

In addition to Start.io ( Formerly StartApp) disclosure / consent box, as required under GDPR, you should report to us users’ consent by consent flag (“pas”), via the API detailed herein below,.

The user consent flag indicates whether a user based in the EU has provided consent for sharing his app data for the purpose of ads personalization. Based on this consent flag, Start.io will target the most relevant ads to your users. If a user has not consented, we will not show personalized ads to this user.

Use this method in case the user has consented:

StartAppSDK.setUserConsent (this,  
                            "pas",
                            System.currentTimeMillis(),                        
                            true);

StartAppSDK.setUserConsent (this,
                            "pas",
                            System.currentTimeMillis(),
                            true)

Use this method in case the user has not consented:

StartAppSDK.setUserConsent (this,  
                            "pas",
                            System.currentTimeMillis(),                        
                            false);

StartAppSDK.setUserConsent (this,
                            "pas",
                            System.currentTimeMillis(),
                            false)

NOTE: timestamp parameter should represent the specific time a consent was given by the user.

To make the process easier, we have added a consent window to our demo apps. Please follow the link to see demo projects. 

CCPA Compliance

Start.io’s SDK (Version 4.9.0 and above) supports publishers to restrict the sale of end users’ personal information under the California Consumer Privacy Act (CCPA).

The notification about opt-out of specific users located in California should be handled based on IAB US Privacy String.

To set the IAB US privacy string, use the following API:

StartAppSDK.getExtras(this)  
    .edit()
    .putString("IABUSPrivacy_String", "1YNN")
    .apply();

StartAppSDK.getExtras(this)
    .edit()
    .putString("IABUSPrivacy_String", "1YNN")
    .apply()

To determine what value to use for the US Privacy String, refer to IAB document. Note that it is case-sensitive.
Example values:

• When CCPA does not apply (for example if the user is not a resident of California) you can either skip this API or use the following value “1---".
• If the user chooses NOT to opt-out, and is ok with advertising, as usual, you can use "1YNN".
• If the user chooses to restrict advertising and opt-out, you can use "1YYN".

For more information on Start.io and CCPA, refer to Start.io’s Blog Page.

Ad Formats

Splash Ad (recommended)

A Splash Ad is a full-page ad that is displayed immediately after the application is launched. A Splash Ad first displays a full page splash screen that you define (as described below) followed by a full page ad.

<meta-data
        android:name="com.startapp.sdk.SPLASH_ENABLED"
        android:value="false" />

By default, your application will be using a pre-defined splash screen designed by Start.io. If you want to customize this screen or if you already have your own splash screen and want to use it, please refer to the Advanced Usage.

Return Ad

The Return Ad is a new ad unit which is displayed once the user returns to your application after a certain period of time. To minimize the intrusiveness, short time periods are ignored.

Return ads are enabled and activated by default. If you want to disable this feature, simply pass "false" as the 3th parameter of the StartAppSDK.init method:

StartAppSDK.init(this, "StartApp App ID", false);

StartAppSDK.init(this, "StartApp App ID", false)

Interstitial Ads

Interstitial Ads are full page ads, displayed before or after a certain content page or action, such as upon entering a stage, between stages, while waiting for an action, upon exiting the application and more. There are three ways of integrating Interstitial Ads:
Exit Ads - show an ad upon exiting your application
Standard Interstitial Ads - show an ad at a specific location(s) in your application
Autostitial Ads - show an ad automatically between activities

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(this) BEFORE the method super.onBackPressed() (this is the activity/application context):

@Override
public void onBackPressed() {
  StartAppAd.onBackPressed(this);
  super.onBackPressed();
}

override fun onBackPressed() {
  StartAppAd.onBackPressed(this)
  super.onBackPressed()
}

Standard Interstitials

Use the showAd()  method to show an Interstitial Ad at a specific location inside your app.

Call StartAppAd.showAd(this) in the appropriate place(s) in the activity where you would like to show the Ad. The showAd method returns true in case the ad was displayed successfully, or false if not (for example, if an ad isn't ready yet).

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

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

fun btnOpenActivity(view: View?) {
    val nextActivity = Intent(this, NextActivity::class.java)
    startActivity(nextActivity)
    StartAppAd.showAd(this)
}

Please notice - If you want to use Autostitial Ads and yet to show an Interstitial in a specific location, call StartAppAd.disbleAutoInterstitial(); before calling StartAppAd.showAd, otherwise two ads might be displayed together. Remember to call StartAppAd.enableAutoInterstitial(); afterthat to reanable Autostitial Ads.

Autostitials

"Autostitial" stands for "Auto Interstitial"; use this integration to show an Interstitial Ad each time an activity is changed.
Simply call StartAppAd.enableAutoInterstitial(); after calling StartAppSDK.init. You can gain more control over the frequency of Autostitial Ads using two methods: time frequency and activity frequency.

Time Frequency

You can set a minimum time interval between consecutive Autostitial Ads.
For example, set a 1 minute interval between two consecutive ads (time in seconds):

StartAppAd.setAutoInterstitialPreferences(
                  new AutoInterstitialPreferences()
                  .setSecondsBetweenAds(60)
           );

StartAppAd.setAutoInterstitialPreferences(
    AutoInterstitialPreferences()
        .setSecondsBetweenAds(60)
)

Activity Frequency

You can set a minimum number of activities between consecutive Autostitial Ads.
For example, show an Autostitial after each 3 activities:

StartAppAd.setAutoInterstitialPreferences(
                  new AutoInterstitialPreferences()
                  .setActivitiesBetweenAds(3)
           );

StartAppAd.setAutoInterstitialPreferences(
    AutoInterstitialPreferences().setActivitiesBetweenAds(3)
)

Time frequency and activity frequency can be used together.

Banner Ads

Add the following View inside your Activity layout XML

<com.startapp.sdk.ads.banner.Banner
 android:id="@+id/startAppBanner"
 android:layout_width="wrap_content"
 android:layout_height="wrap_content"
 android:layout_centerHorizontal="true" />

For a full integration guide, please refer to the Advanced Usage page.

MRec Ads

MRec is a 300X250 rectangular ad integrated within an app's layout. The ad will be refreshed automatically.

Add the following View inside your Activity layout XML:

<com.startapp.sdk.ads.banner.Mrec
 android:id="@+id/startAppMrec"
 android:layout_width="wrap_content"
 android:layout_height="wrap_content"
 android:layout_centerHorizontal="true" />

For adding MRec programmatically, instead of using the layout XML:

// Get the Main relative layout of the entire activity
RelativeLayout mainLayout = (RelativeLayout)findViewById(R.id.mainLayout);

// Define StartApp Mrec
Mrec startAppMrec = new Mrec(this);
RelativeLayout.LayoutParams mrecParameters =
            new RelativeLayout.LayoutParams(
                        RelativeLayout.LayoutParams.WRAP_CONTENT,
                        RelativeLayout.LayoutParams.WRAP_CONTENT);
mrecParameters.addRule(RelativeLayout.CENTER_HORIZONTAL);
mrecParameters.addRule(RelativeLayout.ALIGN_PARENT_BOTTOM);

// Add to main Layout
mainLayout.addView(startAppMrec, mrecParameters);

// Get the Main relative layout of the entire activity
val mainLayout = findViewById(R.id.mainLayout)
// Define StartApp Mrec
val startAppMrec = Mrec(this)
val mrecParameters: RelativeLayout.LayoutParams = RelativeLayout.LayoutParams(
    RelativeLayout.LayoutParams.WRAP_CONTENT,
    RelativeLayout.LayoutParams.WRAP_CONTENT
)
mrecParameters.addRule(RelativeLayout.CENTER_HORIZONTAL)
mrecParameters.addRule(RelativeLayout.ALIGN_PARENT_BOTTOM)
// Add to main Layout
mainLayout.addView(startAppMrec, mrecParameters)

Cover Ads

Cover is a 1200X628 px. (300x157 DP)  rectangular ad integrated within an app's layout. The ad will be refreshed automatically.

Add the following View inside your Activity layout XML:

<com.startapp.sdk.ads.banner.Cover
 android:id="@+id/startAppCover"
 android:layout_width="wrap_content"
 android:layout_height="wrap_content"
 android:layout_centerHorizontal="true" />

For adding Cover programmatically, instead of using the layout XML:

// Get the Main relative layout of the entire activity
RelativeLayout mainLayout = (RelativeLayout)findViewById(R.id.mainLayout);

// Define StartApp Cover
Cover startAppCover = new Cover(this);
RelativeLayout.LayoutParams coverParameters =
            new RelativeLayout.LayoutParams(
                        RelativeLayout.LayoutParams.WRAP_CONTENT,
                        RelativeLayout.LayoutParams.WRAP_CONTENT);
coverParameters.addRule(RelativeLayout.CENTER_HORIZONTAL);
coverParameters.addRule(RelativeLayout.ALIGN_PARENT_BOTTOM);

// Add to main Layout
mainLayout.addView(startAppCover, coverParameters);

// Get the Main relative layout of the entire activity
val mainLayout = findViewById(R.id.mainLayout)
// Define StartApp Cover
val startAppCover = Cover(this)
val coverParameters: RelativeLayout.LayoutParams = RelativeLayout.LayoutParams(
    RelativeLayout.LayoutParams.WRAP_CONTENT,
    RelativeLayout.LayoutParams.WRAP_CONTENT
)
coverParameters.addRule(RelativeLayout.CENTER_HORIZONTAL)
coverParameters.addRule(RelativeLayout.ALIGN_PARENT_BOTTOM)
// Add to main Layout
mainLayout.addView(startAppCover, coverParameters)

Rewarded Video Ads

Rewarded Ads are interstitial video ads that provide a reward to the user in exchange for watching an entire video ad. The reward might be in-app goods, virtual currency or any premium content provided by the application. Because users actually opt-in to watch a rewarded video and are granted with something valuable in return, Rewarded Ads are an effective and clean monetization solution for stronger user retention and keeping users engaged in your application for a longer amount of time.

In order to show a Rewarded Ad, pass the following AdMode parameter when calling the loadAd() method:

startAppAd.loadAd(AdMode.REWARDED_VIDEO);

startAppAd.loadAd(AdMode.REWARDED_VIDEO)

Implement the following listener in order to get a callback when the user completes watching the video and is eligible for getting the reward:

startAppAd.setVideoListener(new VideoListener() {
     @Override
     public void onVideoCompleted() {
          // Grant user with the reward
     }
});

startAppAd.setVideoListener {
    // Grant user with the reward
}

Native Ads

A "Native Ad" is a raw representation of an ad without any pre-defined wrapping UI, which gives you the freedom to design and control the ad exactly as you want. Using Native Ads, you can design an ad experience that perfectly fits your application's scene, content and functionality.

For a full integration guide, please refer to the "Using Native Ads" section under the "Advanced Usage" page.

App-ads.txt

What is app-ads.txt?

With a goal of increasing transparency to the mobile advertising echo system, IAB Tech Lab released app-ads.txt.

App-ads.txt allows the publishers to declare who is officially authorized to sell their inventory, this in return, allows the buyers to purchase the same inventory with confidence in terms of it's legitimacy and authenticity. 

Adding App-ads.txt with Start.io

At Start.io ( Formerly StartApp) we strive to comply with the highest industry standards, we strongly encourage you to add Start.io entries to your app-ads.txt file.
In order to do so, you need to simply follow the instructions in this article. 

Sample Project

Start.io (Formerly StartApp) provides a sample integration project available on "GitHub"

Advanced Usage

For advanced usage, please refer to the "Advanced Usage"