Change Log

Freestar provides an effective ad mediation solution. The Freestar mediation method is universal auction, not the traditional waterfall. Universal auction is more sophisticated than waterfall and provides, by far, the best eCPM. This document describes how to integrate the Freestar SDK into your native Android app quickly and easily. This repo is a fully integrated Android sample app. Feel free to clone it, open with Android Studio and run it on a device.

Note: You can remotely toggle on/off any of the following ad providers as you see fit using our web dashboard. All applicable providers are enabled by default.

Merge in the following repositories to your TOP-LEVEL build.gradle:

https://github.com/freestarcapital/SDK_documentation_Android/blob/master/build.gradle (top-level build.gradle example)

repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
        maven { url 'https://freestar.jfrog.io/artifactory/freestar-mediation-android-sdk' }
        maven { url 'https://s3.amazonaws.com/moat-sdk-builds' }
        maven { url 'https://sdk.tapjoy.com/' }
        maven { url 'https://artifact.bytedance.com/repository/pangle' }
        maven { url 'https://hyprmx.jfrog.io/artifactory/hyprmx' }
        maven { url 'https://adsbynimbus-public.s3.amazonaws.com/android/sdks' } 
        maven { url "https://maven.ogury.co" }
        maven { url "https://s3.amazonaws.com/smaato-sdk-releases/" }
        maven { url "https://sdk-android-prod.launch.liveramp.com" }
}

Use build tools version 4.0.1 or greater:

buildscript {

    dependencies {
        classpath("com.android.tools.build:gradle:4.0.1")  //Make sure to use 4.0.1 or greater
        // NOTE: Do not place your application dependencies here; they belong
        // in the individual module build.gradle files
    }
}

Merge the following into your APP-LEVEL build.gradle:

android {

    compileSdkVersion 33 (or greater)
    
    defaultConfig {

        minSdkVersion 21  //Important: 21 is the minimum SDK int level supported!
        targetSdkVersion 33 (or greater)
   
    }

    compileOptions { 

        sourceCompatibility JavaVersion.VERSION_1_8 
        targetCompatibility JavaVersion.VERSION_1_8 

    }

    packagingOptions {
        exclude 'META-INF/*.kotlin_module'
    }

}

Merge the following dependencies into your APP-LEVEL build.gradle:

https://github.com/freestarcapital/SDK_documentation_Android/blob/master/app/build.gradle (example app-level build.gradle)

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])

    //begin Freestar
    implementation 'com.freestar.android.ads:freestar:5.2.0'
    implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
    implementation 'androidx.lifecycle:lifecycle-viewmodel-ktx:2.5.1'
    implementation 'androidx.lifecycle:lifecycle-common-java8:2.5.1'
    implementation 'androidx.lifecycle:lifecycle-runtime:2.5.1'
    implementation 'androidx.lifecycle:lifecycle-process:2.5.1'

    //Freestar Ad Quality (optional)
    implementation 'com.freestar.android.ads.quality:quality:5.0.3.2'

    //Freestar Identity (optional)
    implementation 'com.freestar.android.ads.identity:identity:2.0.6'
    implementation 'com.liveramp:ats:v2.1.0'
    implementation "androidx.preference:preference-ktx:1.2.0"
    implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.2.0"
    implementation "com.squareup.retrofit2:retrofit:2.9.0"
    implementation "com.jakewharton.retrofit:retrofit2-kotlinx-serialization-converter:0.8.0"
    implementation "androidx.room:room-runtime:2.5.2"
    annotationProcessor "androidx.room:room-compiler:2.5.2"
    implementation "androidx.room:room-ktx:2.5.2"

    //Google Ads Manager (GAM)
    implementation 'com.freestar.android.ads.google:freestar-google-adapter:22.4.0.0'
    implementation 'com.google.android.gms:play-services-ads:22.4.0'

    //AdMob
    implementation 'com.freestar.android.ads.admob:freestar-admob-adapter:22.4.0.0'
    implementation 'com.google.android.gms:play-services-ads:22.4.0'  //can remove if already used

    //GAM mediation adapters
    implementation 'com.google.ads.mediation:applovin:11.11.3.0'
    implementation 'com.google.ads.mediation:adcolony:4.8.0.0'
    implementation 'com.google.ads.mediation:tapjoy:13.1.2.0'
    implementation 'com.google.ads.mediation:facebook:6.16.0.0'
    implementation 'com.facebook.android:audience-network-sdk:6.16.0' //req'd for mediation in GAM

    //AppLovinMAX
    implementation 'com.freestar.android.ads.applovinmax:freestar-applovinmax-adapter:11.11.3.0'
    implementation 'com.applovin:applovin-sdk:11.11.3'

    //AppLovin
    implementation 'com.freestar.android.ads.applovin:freestar-applovin-adapter:11.11.3.0'
    implementation 'com.applovin:applovin-sdk:11.11.3' //can remove if already used

    //Amazon TAM (Transparent Ads Marketplace)
    implementation 'com.freestar.android.ads.tam:freestar-tam-adapter:9.8.2.0'
    implementation 'com.amazon.android:aps-sdk:9.8.2'

    //AdColony
    implementation 'com.freestar.android.ads.adcolony:freestar-adcolony-adapter:4.8.0.0'
    implementation 'com.adcolony:sdk:4.8.0'

    //Criteo
    implementation 'com.freestar.android.ads.criteo:freestar-criteo-adapter:4.4.0.2'
    implementation 'com.criteo.publisher:criteo-publisher-sdk:4.4.0'

    //Unity Ads
    implementation 'com.freestar.android.ads.unityads:freestar-unity-adapter:4.7.1.0'
    implementation "androidx.webkit:webkit:1.7.0"

    //Vungle
    implementation 'com.freestar.android.ads.vungle:freestar-vungle-adapter:6.12.1.0'
    implementation 'com.vungle:publisher-sdk-android:6.12.1'

    //Tapjoy
    implementation 'com.freestar.android.ads.tapjoy:freestar-tapjoy-adapter:13.0.1.0'
    implementation 'com.tapjoy:tapjoy-android-sdk:13.0.1@aar'

    //Nimbus
    implementation 'com.freestar.android.ads.nimbus:freestar-nimbus-adapter:2.10.0.2'
    implementation "com.adsbynimbus.android:nimbus:2.10.0"
    implementation "com.adsbynimbus.android:extension-facebook:2.10.0"

    //Pangle
    implementation 'com.freestar.android.ads.pangle:freestar-pangle-adapter:3.7.1.6'
    implementation 'com.pangle.global:ads-sdk:3.7.1.4'

    //Prebid
    implementation 'com.freestar.android.ads.prebid:freestar-prebid-adapter:2.1.1.4'
    implementation 'com.freestar.android.ads.prebid:freestar-prebid-core:2.1.1.1'
    implementation 'com.google.android.exoplayer:exoplayer-core:2.19.0'
    implementation 'com.google.android.exoplayer:exoplayer-ui:2.19.0'
    implementation 'com.google.android.exoplayer:extension-ima:2.19.0'
    implementation "androidx.localbroadcastmanager:localbroadcastmanager:1.1.0"

    //HyprMX
    implementation 'com.freestar.android.ads.hyprmx:freestar-hyprmx-adapter:6.0.3.1'
    implementation 'com.hyprmx.android:HyprMX-SDK:6.0.3'

    //Ogury
    implementation 'com.freestar.android.ads.ogury:freestar-ogury-adapter:5.4.0.0'
    implementation 'co.ogury:ogury-sdk:5.4.0'

    //Fyber
    implementation 'com.freestar.android.ads.fyber:freestar-fyber-adapter:8.2.3.0'
    implementation 'com.fyber:marketplace-sdk:8.2.3'

    //Smaato
    implementation 'com.freestar.android.ads.smaato:freestar-smaato-adapter:22.1.1.3'
    implementation 'com.smaato.android.sdk:smaato-sdk:22.3.1'
    implementation 'com.smaato.android.sdk:smaato-sdk-native:22.3.1'
    implementation 'com.smaato.android.sdk:smaato-sdk-banner:22.3.1'
    implementation 'com.smaato.android.sdk:smaato-sdk-interstitial:22.3.1'
    implementation 'com.smaato.android.sdk:smaato-sdk-rewarded-ads:22.3.1'


    //uncomment if your app is a React Native app
    //implementation 'com.freestar.android.ads:react-native-android:1.2.1'

    //Note: If you want to use Preroll video ads, un-comment the following lines:
    //Important: Preroll is not compatible with Nimbus, so remove all 3 Nimbus
    //dependencies (above) before using Preroll video ads (freestar-nimbus-adapter,
    //and nimbus section).
    //start preroll
    //implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.28.0'
    //implementation 'com.google.android.exoplayer:exoplayer-core:2.19.0'
    //implementation 'com.google.android.exoplayer:exoplayer-ui:2.19.0'
    //implementation 'com.google.android.exoplayer:extension-ima:2.19.0'
    //end preroll

    //end, FreeStar
    

Note: The values will be different for your final production build.

Merge the following <meta-data> tags into the <application> tag of your AndroidManifest.xml

• Include android:networkSecurityConfig="@xml/network_security_config" in the application property tag.
• Add android:exported="true" to your MainActivity activity tag (Your main launcher activity):

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.yourcompany.yourapp">


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

   <application 
        ...
        android:networkSecurityConfig="@xml/network_security_config" />

        <activity
            android:exported="true"
            android:name=".MainActivity"
            ...
        </activity>
        
       <meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version"/>

       <meta-data
            android:name="com.google.android.gms.ads.APPLICATION_ID"
            android:value="ca-app-pub-3940256099942544~3347511713"/>

       <meta-data android:name="applovin.sdk.key"
            android:value="hO52kFtMvEo_AoeRzED0_XXfS1B1VQp9GW50yudJO-eUUTOmRBLl3c-2GyTevLNspll_fN5PLTbAHOakoTuHuP"/>

   </application>

See the AndroidManifest.xml:

https://github.com/freestarcapital/SDK_documentation_Android/blob/master/app/src/main/AndroidManifest.xml

Add network_security_config.xml to the [ProjectRoot]/app/src/main/res/xml folder (If folder does not exist, please create it).

Freestar Ads must be initialized before you start requesting ads.

        import com.freestar.android.ads.AdRequest;
        import com.freestar.android.ads.FreeStarAds;


        //You may use application or activity context (activity context is preferred due to multiple partners)
        adRequest = new AdRequest(context);
        adRequest.addCustomTargeting("some target", "my value"); //optional
        FreeStarAds.init(context, "XqjhRR", adRequest);    //Use our test key until our solutions team creates your own key!

        //If you do not have custom targeting parameters, then you
        //can just call FreeStarAds.init(context, "XqjhRR")

Freestar Ads allows for custom targeting parameters that will be sent to our Google Ads Manager adapter.

        adRequest = new AdRequest(context);
        adRequest.addCustomTargeting("target1", "value1"); //optional
        adRequest.addCustomTargeting("target2", "value2"); //optional

App Open Ad is a fullscreen ad that shows when the app starts (including 'cold starts') and when the app is resumed from the background.

To utilize App Open Ads in your application, call the following method before calling FreeStarAds.init as follows:

FreeStarAds.requestAppOpenAds("app-open-ad-placement", true, null);   //Obtain a proper placement from our Solutions Team
FreeStarAds.init(...);

Note: Please do not "prefetch" the next interstial ad on app startup or after dismissals or no-fills; we do this automatically and internally for you.

InterstitialAd interstitialAd = new InterstitialAd(this, this); //Requires Activity context
interstitialAd.loadAd(adRequest);

//You can also load associated to a placement as follows
//interstitialAd.loadAd(adRequest, "my_placement_p1"); 

If you plan to use more than one placement in your app, please adhere to the placement naming convention as follows:

"my_placement_name_pN", where N is the number of your placement.

For example, let us assume you are using 2 interstitial ad placements in your game or app. The first placement would be the default placement; simply do not specifiy a placement name by using the loadAd() method without the placement parameter. The second placement would be, for example, "my_search_screen_p1". The ending "p1" tells the SDK to use the second placement you created in our web dashboard for the interstitial ad unit.

This process is the same for all the other ad units, such as rewarded ads and banner ads.

When the interstitial ad is ready, the onInterstitialLoaded callback will occur.

    @Override
    public void onInterstitialLoaded(String placement) {
        interstitialAd.show();  //You can display the ad now OR show it later; your choice.
        
        //Note: Placement will be null if not specified in the original loadAd request.
        
    }

There are other callbacks that will occur in other events, such as in the rare event where a load ad request does not result in a fill. Please see the MainActivity on this sample for those details.

❗⚠Warning: Attempting to load a new ad from the onInterstitialFailed() method is strongly discouraged. If you must load an ad from onInterstitialFailed(), limit ad load retries to avoid continuous failed ad requests in situations such as limited network connectivity.

Freestar supports 300x250 and 320x50 banner ad formats and allows you to control the refresh intervals remotely.

        BannerAd bannerAd = new BannerAd(this);  //in Activity
        bannerAd.setAdSize(AdSize.BANNER_320_50);
        bannerAd.loadAd(adRequest);
        
        //Note: you may pass in a "placement" parameter in loadAd but it requires prior remote staff setup
        

When the banner ad is ready, the onBannerAdLoaded callback will occur.

    @Override
    public void onBannerAdLoaded(View bannerAd, String placement) {

        //Note: Placement will be null if not specified in the original loadAd request.
        //'banner_container' is your ad container

        ((ViewGroup) findViewById(R.id.banner_container)).removeAllViews();
        ((ViewGroup) findViewById(R.id.banner_container)).addView(bannerAd);   //You MUST add the banner to your container here!
   
    }

Another way to display banner ads is to put BannerAd directly into your XML layout as follows. NOTE: If you choose this route, then you do not need any code in java or kotlin as the ad will automatically be fetched. Also, if you need to set targeting parameters in the AdRequest, then please use the programmatic approach and do not put the banner in the layout.

See com.freestar.android.ads.BannerAd in the sample layout:

https://github.com/freestarcapital/SDK_documentation_Android/blob/master/app/src/main/res/layout/activity_main.xml

Small Banner Example:

            <com.freestar.android.ads.BannerAd xmlns:ads="http://schemas.android.com/apk/res-auto"
            android:id="@+id/freestarBannerAd_2"
            android:layout_width="320dp"
            android:layout_height="50dp"
            ads:FreeStarAdSize="BANNER"/>

MREC Example:

            <com.freestar.android.ads.BannerAd xmlns:ads="http://schemas.android.com/apk/res-auto"
            android:id="@+id/freestarBannerAd_2"
            android:layout_width="300dp"
            android:layout_height="250dp"
            ads:FreeStarAdSize="MEDIUM_RECTANGLE"/>

Leaderboard Example:

            <com.freestar.android.ads.BannerAd xmlns:ads="http://schemas.android.com/apk/res-auto"
            android:id="@+id/freestarBannerAd_2"
            android:layout_width="728dp"
            android:layout_height="90dp"
            ads:FreeStarAdSize="LEADERBOARD"/>

Another feature added to MREC Banner Ads (300x250) is the ability to backfill with Small Banner Ads (320x50). This feature is also controllable via the admin dashboard and is not enabled by default.

The following is sample code illustrating how to render these new MREC features:

        BannerAd bannerAd = new BannerAd(activity);
        bannerAd.setOnBannerAdSizeChangedListener(OnBannerAdSizeChangedListener);
        bannerAd.setAdSize(AdSize.MEDIUM_RECTANGLE_300_250);
        bannerAd.loadAd(request);

    @Override
    public void onBannerAdSizeChanged(AdSize adSize, boolean isNativeAd) {
        Logger.i(TAG,"onBannerAdSizeChanged: " + adSize + " isNative: " + isNativeAd);
        if (adSize.equals(AdSize.NATIVE)) {
            findViewById(R.id.mrec_container)
                    .setLayoutParams(new LinearLayout.LayoutParams(dpToPx(350),dpToPx(280)));
        } else if (adSize.equals(AdSize.BANNER_320_50)) {
            findViewById(R.id.mrec_container)
                    .setLayoutParams(new LinearLayout.LayoutParams(dpToPx(320),dpToPx(50)));
        } else if (adSize.equals(AdSize.MEDIUM_RECTANGLE_300_250)) { //mrec
            findViewById(R.id.mrec_container)
                    .setLayoutParams(new LinearLayout.LayoutParams(dpToPx(300),dpToPx(250)));
        }
    }

The above is taken from our sample app code.

Freestar now supports Adaptive Banner Ads, which are 320x50 banner ads that will automatically fill the full width of the device. AdMob and Google Ads Manager are two supporting demand source partners at this time.
To start displaying Adaptive Banner Ads today, follow the same instructions per our standard banner ads (above). We recommend setting your ad container dimensions to WRAP_CONTENT x WRAP_CONTENT. Then, call the following method before or after our init method:

FreeStarAds.init(...);
FreeStarAds.showAdaptiveBannerAdsWhenAvailable( true );  //default is false

So, using Adaptive Banner Ads is not much different from our standard 320x50 banner ads.

NOTE: If there is no-fill for Adaptive Banner (from AdMob or Google Ads Manager), then Freestar will fallback to the standard sized banner ad (320x50) provided by our other demand source partners. You may receive a banner ad that fills the full width of the screen OR you may get a banner ad that fills 320x50.

Note: Please do not "prefetch" the next rewarded ad on app startup or after dismissals or no-fills; we do this automatically and internally for you.

A common myth regarding Rewarded Ads is publishers are required to give something to the user. But, that's not true. You can simply tell the user they must watch the ad in order to be able to proceed to the next level or proceed to content.

  RewardedAd rewardedAd = new RewardedAd(this, this); //Must use Activity context
  rewardedAd.loadAd(adRequest);

//You can also load an ad tied to an Interstitial 'placement' as follows
//rewardedAd.loadAd(adRequest, "my_placement_p1"); //'placement' is OPTIONAL and only if 
                                                       //you plan to have more than one Rewarded
                                                       //placement

When the rewarded ad is ready, the onRewardedVideoLoaded callback will occur.

    @Override
    public void onRewardedVideoLoaded(String placement) {
        rewardedAd.showRewardAd("my_optional_secret", "my_optional_userid", "Gold Coins", "100");  //Display Ad
        
        //Note: Placement will be null if not specified in the original loadAd request.

        //Note: If you want to use server-to-server rewarded callbacks, the Freestar team will provide
        //      you with a secret and only that will work.
        //      However, if you want to use client-side only rewarded callbacks, then you can supply
        //      your own "secret" or null as the first parameter.
    }

When the user has fully watched the rewarded ad, the following callback will occur:

    @Override
    public void onRewardedVideoCompleted(String placement) {
       //allow user to proceed to app content or next level in app/game
    }

When the user has closed the rewarded ad, the following callback will occur:

    @Override
    public void onRewardedVideoDismissed(String placement) {

    }

If the user does not watch the rewarded ad thru to completion, onRewardedVideoCompleted will not occur. However, the onRewardedVideoDismissed will always occur when the rewarded ad is dismissed regardless if the user watched the entire rewarded ad or not.

❗⚠ Please assume that ads will expire in about 1 hour after the loaded callback. Meaning, you may cache an ad in your app or game, but must be displayed within the alloted hour. Also note that some SDK partners, at their own discretion, may expire their ads earlier than one hour.

Freestar supports Native Ad format where you may customize the look and feel of the ad itself.

Freestar supports Thumbnail Ads. These are small, floating box ads that overlay your application content. They are not part of your layout design, but you can choose their initial screen location when they first appear. Users can drag them around and can close them via an 'X' button, similar to YouTube 'mini-player' mode.

        import com.freestar.android.ads.AdRequest;
        import com.freestar.android.ads.ThumbnailAd;
        import com.freestar.android.ads.ThumbnailAdGravity;
        import com.freestar.android.ads.ThumbnailAdListener;

        ...

        AdRequest adRequest = new AdRequest(context);
        ThumbnailAd thumbnailAd = new ThumbnailAd(context);
        thumbnailAd.setListener(...);
        thumbnailAd.loadAd(adRequest);        

In your listener implementation:

    @Override
    public void onThumbnailAdLoaded(String placement) {       
        thumbnailAd.setGravity(ThumbnailAdGravity.topLeft);  //optional initial location; default is bottomLeft
        thumbnailAd.setMargins(10,10); //in DP               //optional margins in DP; default is 0 and 0
        thumbnailAd.show();
    }

A PaidEvent occurs when an ad is shown on the screen. PaidEvent contains the following information:

There are two ways to listen for PaidEvents; either by setting a global OnPaidEvent handler or individually per each ad unit type request:

FreeStarAds.setOnPaidEventListener( [Your Global OnPaidEvent handler] );

or

BannerAd bannerAd = new BannerAd();
bannerAd.setOnPaidEventListener( [Your OnPaidEvent handler for this Banner Ad] );

OnPaidEventListener can be set on any ad unit type, not just BannerAd.

https://github.com/freestarcapital/SDK_documentation_Android/blob/master/app/src/main/java/com/freestar/android/sample/MainActivity.java