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.

Supported Ad Partners

Getting Started

Follow the simple steps below to start monetizing with Freestar Ads in your native Android app today!

Project Setup

Modify Gradle

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://artifactory.verizonmedia.com/artifactory/maven/' }    
}

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
    }
}

Modify app-level build.gradle

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

android {

    compileSdkVersion 31
    
    defaultConfig {

        minSdkVersion 19  //Important: 19 is the minimum SDK int level supported!
        targetSdkVersion 31 
   
        multiDexEnabled true
    }

    compileOptions { 

        sourceCompatibility JavaVersion.VERSION_1_8 
        targetCompatibility JavaVersion.VERSION_1_8 

    }

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

}

Dependencies

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:4.6.4'
    implementation 'com.freestar.android.ads.admob:freestar-admob-adapter:20.6.0.0'
    implementation 'com.freestar.android.ads.applovin:freestar-applovin-adapter:11.2.2.0'
    implementation 'com.freestar.android.ads.applovinmax:freestar-applovinmax-adapter:11.2.2.0'
    implementation 'com.freestar.android.ads.tam:freestar-tam-adapter:8.4.3.3'
    implementation 'com.freestar.android.ads.adcolony:freestar-adcolony-adapter:4.6.5.0'
    implementation 'com.freestar.android.ads.google:freestar-google-adapter:20.6.0.0'
    implementation 'com.freestar.android.ads.criteo:freestar-criteo-adapter:4.2.1.2'
    implementation 'com.freestar.android.ads.unityads:freestar-unity-adapter:4.1.0.0'
    implementation 'com.freestar.android.ads.vungle:freestar-vungle-adapter:6.10.4.0'
    implementation 'com.freestar.android.ads.tapjoy:freestar-tapjoy-adapter:12.2.1.1'
    implementation 'com.freestar.android.ads.nimbus:freestar-nimbus-adapter:1.10.4.1'
    implementation 'com.freestar.android.ads.pangle:freestar-pangle-adapter:3.6.0.0'
    implementation 'com.freestar.android.ads.hyprmx:freestar-hyprmx-adapter:6.0.1.0'
    implementation 'com.freestar.android.ads.yahoo:freestar-yahoo-adapter:1.14.0.0'

    implementation 'com.applovin:applovin-sdk:11.3.1'
    implementation 'com.criteo.publisher:criteo-publisher-sdk:4.4.0'
    implementation 'com.google.android.gms:play-services-ads:20.6.0'
    implementation 'com.google.ads.mediation:facebook:6.8.0.0' //fb fill via gam
    //implementation('com.google.android.ads.consent:consent-library:1.0.8') {
    //    exclude group: 'com.android.support'
    //    exclude group: 'com.google.code.gson', module: 'gson'
    //}
    implementation('com.facebook.android:audience-network-sdk:6.8.0') {
        exclude group: 'com.google.android.exoplayer'
        exclude group: 'com.google.android.gms'
        exclude group: 'com.android.support'
    }
    implementation 'com.tapjoy:tapjoy-android-sdk:12.4.2@aar'
    implementation 'com.vungle:publisher-sdk-android:6.10.4'
    implementation 'androidx.constraintlayout:constraintlayout:2.0.4' //new dependency requirement

    //Note: if you are using Preroll, un-comment the following lines:
    //start preroll
    /*
    implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.23.0'
    implementation 'com.google.android.exoplayer:exoplayer-core:2.13.3'
    implementation 'com.google.android.exoplayer:exoplayer-ui:2.13.3'
    implementation 'com.google.android.exoplayer:extension-ima:2.13.3'
    */
    //end preroll

    //nimbus
    implementation "com.adsbynimbus.android:nimbus:1.10.4" // Full Nimbus SDK with NimbusAdManager
    implementation "com.adsbynimbus.android:extension-okhttp:1.10.4" // Use OkHttp with NimbusAdManager
    implementation "com.adsbynimbus.android:extension-facebook:1.10.4"
    implementation "com.adsbynimbus.openrtb:kotlin:0.7.4"

    //Amazon Transparent Ads Marketplace
    implementation 'com.amazon.android:aps-sdk:9.2.1@aar'

    //Pangle; also requires play-services-ads-identifier but already in Criteo
    implementation 'com.pangle.global:ads-sdk:3.6.0.4'

    //adcolony
    implementation 'com.adcolony:sdk:4.6.5'

    //hyprmx
    implementation 'com.hyprmx.android:HyprMX-SDK:6.0.1'

    //yahoo/verizon
    implementation 'com.verizon.ads:android-vas-standard-edition:1.14.0'
    implementation 'androidx.browser:browser:1.4.0'


    //REACT-NATIVE NOTE: Uncomment the line below if your project is React Native
    //implementation 'com.freestar.android.ads:react-native-android:1.1.1'

    //App Open Ads (startup ads)
    implementation "androidx.lifecycle:lifecycle-runtime:2.4.0"
    implementation "androidx.lifecycle:lifecycle-common-java8:2.4.0"
    implementation "androidx.lifecycle:lifecycle-process:2.4.0"

    //GAM mediation adapters
    implementation 'com.google.ads.mediation:applovin:11.1.2.0'
    implementation 'com.google.ads.mediation:adcolony:4.6.5.0'
    implementation 'com.google.ads.mediation:tapjoy:12.9.0.0'
    implementation 'com.google.ads.mediation:facebook:6.8.0.0'

    //end, Freestar
    

AndroidManifest.xml

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

<?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
        
       <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

Initialize Freestar Ads

Freestar Ads must be initialized before you start requesting ads.

        //You may use application or activity context
        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")

Custom Targeting

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

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(...);

Interstitial Ad

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.

Banner Ad

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

            <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"/>

Adaptive Banner Ad (new)

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.

Rewarded Ad

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.

Preroll Ad

Freestar supports preroll video ads.

        PrerollAd prerollAd = new PrerollAd(this);  //Activity context
        prerollAd.loadAd(adRequest, AdSize.PREROLL_320_480, "optional-placement-string", listener);
       

When the preroll ad is ready, the onPrerollAdLoaded callback will occur:

    @Override
    public void onPrerollAdLoaded(View prerollView, String placement) {

        ((ViewGroup) findViewById(R.id.ad_container)).removeAllViews();
        ((ViewGroup) findViewById(R.id.ad_container)).addView(prerollView); //add view to layout
        prerollAd.showAd();  //play the video ad
   
    }

Additional Preroll Dependencies

As mentioned in the dependencies section above, please take of note of the preroll-specific dependencies.

Please see the MainActivity.java of our sample app at the bottom of this page to see how preroll ads work.

Native Ad Unit

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

Sample Project

All of this and more, such as Preroll Ads can be seen in the sample MainActivity:

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

Privacy - Google Play Families Policy Compliance

If your game or app is officially under the Google Play Families program, Freestar provides such support:

FreeStarAds.setGoogleFamilyPolicyMode( GoogleFamilyPolicyMode.app, true); //If your app is designed only for children
//FreeStarAds.setGoogleFamilyPolicyMode( GoogleFamilyPolicyMode.mixed, false);  //If your app is designed for families with children
FreeStarAds.init(...);

If your app is not officially under the Google Play Families program, then you do not need to set the Google Family Policy mode.

    /**
     * Only set Google Families Policy Mode if your app is required to comply with Google Play’s
     * Families Policy program.
     *
     * @param googleFamilyPolicyMode app: the app is child-directed and will not receive
     *                               personalize or contextual ads.
     *                               mixed: the app is directed at mixed audiences.
     *                               none: (default) the app is not required to comply with Google
     *                                      Play's Family Policy
     *
     * @param onlyNonPersonalizedAds true: if 'mixed' mode, then only personalized or contextual ads
     *                                     may be served.
     *                               false: if 'mixed' mode, then personalized or contextual ads
     *                                      may be served.
     *                               note:  if 'app' mode, then personalized or contextual ads
     *                                      may not be served regardless of this parameter.
     */
    public static void setGoogleFamilyPolicyMode(GoogleFamilyPolicyMode googleFamilyPolicyMode,
                                                 boolean onlyNonPersonalizedAds)

GDPR

Freestar SDK is GDPR compliant. In order for your users to be able to receive any ad fills in GDPR-affected countries, you, as a publisher, will need to implement a 3rd party Consent Management Platform (CMP). Freestar SDK will automatically detect user interactions with the CMP and act accordingly. Please see our Freestar GDPR Frequently Asked Questions for complete details and our recommended list of CMP service providers.

Testing

For Android, please use our test key XqjhRR for all your testing runs and enable test mode true. You will usually get 100% fill on all ad units. It is not recommended to use your production key for testing runs as that is strictly prohibited by our partners and bad things may happen to us on the business side of things.
Do not forget to uninstall and re-install your app when changing keys on your device.

When you are satisfied with your testing, please make a release build with your production key, and turn test mode off. Publish to store.

Automated Testing - Bypassing Ads

Are your automated tests failing after integrating Freestar Mediation Ads into your mobile application or game? Are you not sure it could be due to Freestar or something else? We have a feature called Automated Test Mode where you can run your automated tests to bypass Freestar or run Freestar in 'Limited Mediation' mode without making drastic changes to your code:

In your automated test suite code, before FreeStarAds.init is called:

FreeStarAds.setAutomatedTestMode( FreeStarAds.AutomatedTestMode.BYPASS_ALL_ADS )  
  //OR
FreeStarAds.setAutomatedTestMode( FreeStarAds.AutomatedTestMode.LIMITED_MEDIATION )    //only runs AdMob & GAM

Again, this is only for your automated tests and not for production use.

Release Build

Final note when creating your release build: if you use proguard or minify, please add our proguard rules to your app proguard file.

Welcome to the freestar_flutter_plugin wiki!

The latest version of our plugin can be found here.

Add Freestar Ads Mediation to your Flutter app. Supported on Android and iOS platforms.

Run our sample

A great way to become familiar with Freestar mediation is to run our sample app.

1. If not already done so, install the Flutter development environment by Google!

2. Connect an Android device to your computer. (Don't worry, the plugin also supports iOS!)

3. Open command-shell or terminal window and:

git clone https://github.com/freestarcapital/freestar_flutter_plugin

cd freestar_flutter_plugin/example

flutter run

Getting Started

Follow these steps to integrate Freestar Flutter plugin (freestar_flutter_plugin) package into your Flutter app. The first step will be Dart setup. The Android and iOS sub-sections will follow.

Dart Setup

The following are essentially excerpts from our example main.dart Please take a look to see how easy it is to integrate Freestar mediation.

Initialize Freestar

import 'package:freestar_flutter_plugin/freestar_flutter_plugin.dart';

In your initState method, setup Freestar with the following test keys:

FreestarFlutterPlugin.enableLogging(true);        //set false for production
FreestarFlutterPlugin.enableTestMode(true);       //set false for production
FreestarFlutterPlugin.enablePartnerChooser(true); //set false for production

if (defaultTargetPlatform == TargetPlatform.android) {
  FreestarFlutterPlugin.init("XqjhRR"); //Android Test Key
} else if (defaultTargetPlatform == TargetPlatform.iOS) {
  FreestarFlutterPlugin.init("P8RIA3");  //iOS Test Key
}

Interstitial Ad (Fullscreen ad)

Make sure to implement the InterstitialAdListener interface. For example:

class _MyAppState extends State<MyApp>
    implements InterstitialAdListener

Declare/Instantiate InterstitialAd

InterstitialAd _interstitialAd = new InterstitialAd(); 

// Another way:
InterstitialAd _interstitialAd = InterstitialAd.from('optional-placement', myInterstitialAdListener); 

// Loading
_interstitialAd.interstitialAdListener = myInterstitialAdListener; //if not already set, do so before calling loadAd
_interstitialAd.placement = 'optional-placement';  //optional placement or simply omit if not needed

//optional targeting parameters
Map targetingParams = Map();
targetingParams["my-targeting-param1"] = "example value 1";
targetingParams["my-targeting-param2"] = "example value 2";
_interstitialAd.targetingParams = targetingParams; //optional targeting params or simply omit if not needed

_interstitialAd.loadAd();  //fetches highest-paying mediation partner ad-fill

When you receive the onInterstitialAdLoaded callback, the interstitial ad is ready to be shown:

_interstitialAd.showAd();  //Display fullscreen interstitial ad

Rewarded Ad (Fullscreen ad)

Make sure to implement the RewardedAdListener interface. For example:

class _MyAppState extends State<MyApp>
    implements RewardedAdListener

Declare/Instantiate RewardedAd

RewardedAd _rewardedAd = new RewardedAd(); 

// Another way:
RewardedAd _rewardedAd = RewardedAd.from('optional-placement', myRewardedAdListener); 

// Loading
_rewardedAd.rewardedAdListener = myRewardedAdListener; //if not already set, do so before calling loadAd
_rewardedAd.placement = 'optional-placement';  //optional placement or simply omit if not needed

//optional targeting parameters
Map targetingParams = Map();
targetingParams["my-targeting-param1"] = "example value 1";
targetingParams["my-targeting-param2"] = "example value 2";
_rewardedAd.targetingParams = targetingParams; //optional targeting params or simply omit if not needed

_rewardedAd.loadAd();  //fetches highest-paying mediation partner ad-fill

When you receive the onRewardedAdLoaded callback, the Rewarded ad is ready to be shown:

//secret - the secret string you want to secure your reward with
//userId - your user id string.  can use empty string ""
//rewardType - can be "Gold" or "Coins" or whatever your virtual currency may be!
//rewardAmount - whatever string amount your user will be rewarded with

_rewardedAd.showAd("my-secret-12345", "myUserId-12345", "V-Bucks", "100");  //Display fullscreen Rewarded ad

When 'onRewardedAdCompleted' is called, this indicates the user has completed viewing the fullscreen rewarded to the end.

Banner Ad

The following banner ad sizes are supported:

BannerAd.AD_SIZE_BANNER_320x50
BannerAd.AD_SIZE_MREC_300x250
BannerAd.AD_SIZE_LEADERBOARD_728x90   (for tablet devices)

Make sure to implement the BannerAdListener interface. For example:

class _MyAppState extends State<MyApp>
    implements BannerAdListener

Declare/Instantiate BannerAd

BannerAd _bannerAd = new BannerAd(); 

// Another way:
BannerAd _bannerAd = BannerAd.from('optional-placement', BannerAd.AD_SIZE_BANNER_320x50, myRewardedAdListener, false);

//The last parameter is `doAutoloadWhenCreated` (see below for reference)

Add BannerAd to your UI

Add the BannerAd to your Scaffold or UI hierarchy:

_bannerAd.bannerAdListener = myBannerAdListener;    //set listener, if not already set
_bannerAd.adSize = BannerAd.AD_SIZE_BANNER_320x50;  //set the banner ad size, if not already not
_bannerAd.doAutoloadWhenCreated = true;  //displays the banner ad as soon as UI is initialized and do not need to call bannerAd.loadAd

//Small banner ad example:
Container(width: 320.0,  //explicitly set the physical container size appropriately
          height: 50.0,
          child: _bannerAd)

//MREC banner ad example:
Container(width: 300.0,  //explicitly set the physical container size appropriately
          height: 250.0,
          child: _mrecBannerAd)

Banner ad also supports optional targeting parameters:

Map targetingParams = Map();
targetingParams["my-targeting-param1"] = "example value 1";
targetingParams["my-targeting-param2"] = "example value 2";
_bannerAd.targetingParams = targetingParams; //optional targeting params or simply omit if not needed

_bannerAd.loadAd();  //fetches highest-paying mediation partner ad-fill

When the a fill is received, the BannerAd will automatically display in the position where it was added to the UI and onBannerAdLoaded will be called.

Native Ad

Native Ads are supported. Out of the box, native ads support two general sizes:

NativeAd.NATIVE_TEMPLATE_SMALL    AND
NativeAd.NATIVE_TEMPLATE_MEDIUM

Make sure to implement the NativeAdListener interface. For example:

class _MyAppState extends State<MyApp>
    implements NativeAdListener

Declare/Instantiate NativeAd

NativeAd _nativeAd = new NativeAd(); 

// Another way:
NativeAd _nativeAd = NativeAd.from('optional-placement', NativeAd.NATIVE_TEMPLATE_SMALL, myNativeAdListener, false);

//The last parameter is `doAutoloadWhenCreated` (see below for reference)

Add NativeAd to your UI

Add the NativeAd to your Scaffold or UI hierarchy:

_nativeAd.nativeAdListener = myNativeAdListener;    //set listener, if not already set
_nativeAd.adSize = NativeAd.NATIVE_TEMPLATE_SMALL;  //set the native ad size, if not already not
_nativeAd.doAutoloadWhenCreated = true;  //displays the native ad as soon as UI is initialized and do not need to call nativeAd.loadAd

//Small template native ad example:
Container(width: window.physicalSize.width,  //fullscreen width
          height: 100.0,  //100.0 is the small native ad height
          child: _smallNativeAd)

//Medium template native ad example:
Container(width: window.physicalSize.width,  //fullscreen width
          height: 350.0,  //350.0 is the medium native ad height
          child: _mediumNativeAd)

Native ad also supports optional targeting parameters:

Map targetingParams = Map();
targetingParams["my-targeting-param1"] = "example value 1";
targetingParams["my-targeting-param2"] = "example value 2";
_nativeAd.targetingParams = targetingParams; //optional targeting params or simply omit if not needed

_nativeAd.loadAd();  //fetches highest-paying mediation partner ad-fill

When the a fill is received, the NativeAd will automatically display in the position where it was added to the UI and onNativeAdLoaded will be called.

Android Setup

Add this section to your app AndroidManifest.xml. More specifically, just the meta-data tags. Using our example, the path would be: freestar_flutter_plugin/example/android/app/src/main/AndroidManifest.xml

When done, you may run your Flutter app on a connected Android device!

Android Proguard

When creating a release version of your Android app, make sure to use our proguard-rules.pro from our flutter sample ads app.

Android plugin dependencies

See our plugin gradle dependencies here

iOS Setup

The flutter build ios command in the terminal will generate an Xcode project from your Flutter app. The generated folder (example/ios) in this repo will include:

• An .xcworkspace file
• An .xcproject file
• A {YOUR_APP_NAME} folder containing generated native code
• A Podfile file
• A Podfile.lock file
• A Pods folder

The last three relate to the CocoaPods system, used both by Flutter and by Freestar to manage iOS library dependencies. To complete the setup, you will need to edit the Podfile with the following changes:

1. Specify the iOS version: platform :ios, '10.0'. This is the minimum supported version. Freestar supports iOS 10.0 and above.
2. In the target '{YOUR_APP_NAME}' section, list the advertsing partners from which you would like to see ads:

  pod 'FreestarAds-AdColony', '~> 5.0'
  pod 'FreestarAds-AppLovin', '~> 5.0'
  pod 'FreestarAds-Googleadmob', '~> 6.0'
  pod 'FreestarAds-Tapjoy', '~> 5.0'
  pod 'FreestarAds-Unity', '~> 6.0'
  pod 'FreestarAds-Vungle', '~> 5.0'
  pod 'FreestarAds-Criteo', '~> 3.0'
  pod 'FreestarAds-GAM', '~> 5.0'
  pod 'FreestarAds-Mopub', '~> 5.0'
  pod 'FreestarAds-Nimbus', '~> 3.0'
  pod 'FreestarAds-TAM', '~> 2.0'
  pod 'FreestarAds-Pangle', '~> 1.0'
  pod 'FreestarAds-Hyprmx', '~> 1.0'

Once you made the changes, save the Podfile, enter the ios directory in the terminal, and re-run pod install. Then open the {YOUR_APP_NAME}.xcworkspace file with Xcode.

The generated project will include an Info.plist file. If, when editing your Podfile (see above), you included either FreestarAds-Googleadmob or FreestarAds-GAM in the partner list, you will need to add your Google Application Identifier (received from Google) to the Info.plist; the app will not function without this:

<key>GADApplicationIdentifier</key>
<string>ca-app-pub-3940256099942544~1458002511</string>

There are also two flags that you can add to the plist to aid in development. To see test ads:

<key>CHP_TEST_ADS</key>
<string>enable</string>

Test ads do not generate revenue, remove this flag before submitting the app to the App Store.

To generate detailed logging from the Freestar SDK:

<key>CHP_LOGGING_ENABLE</key>
<string>true</string>

❗⚠Warning: For both performance and security reasons, it is not advisable to have detailed logging in production apps. Remove the flag in the Info.plist before submitting to the App Store.

When done, you may run your Flutter app on a connected iOS device!

Summary

Integrating Freestar Flutter plugin to display ads in your Flutter app is easy. As mentioned, please see our example main.dart

Freestar Ads Mediation - Unity Integration Guide for Android

Getting Started

Start displaying Freestar Ads in your Unity game today by following the simple steps below.

Requirements

• Unity 2018 or newer

• Minimum Android API Level: 21 or higher

Begin

Please follow the instructions in order.

Make sure you switched to Android:

Unity Player Settings

Other settings: Minimum API Level: 21

Other settings: Target API Level: Highest Installed

Other settings: Api Compatability Level: .NET 4.x

Publisher Settings: Custom Gradle Template ✅

Do Not Install Unity Ads

If you try to use Unity Ads Package with FreestarMediation, this will produce a build-time error because FreestarMediation already contains the Unity Ads library.

Import Custom Package

Download FreestarMediation.unitypackage

Next, we will import it into Unity as a Custom Package.

Assets: Import Package: Custom Package

Hit the Import button.

Resolve Android Dependencies

After importing our custom package, resolve Android dependencies via Assets.. External Dependency Manager... Android Resolver... Resolve.

Manually Edit mainTemplate.gradle

Use your favorite file editor.

Edit [Unity Project Folder]/Assets/Plugins/Android/mainTemplate.gradle

Remove the top line:

// GENERATED BY UNITY. REMOVE THIS COMMENT TO PREVENT OVERWRITING WHEN EXPORTING AGAIN

Add the following to the android root section:

    packagingOptions {
        exclude("META-INF/*.kotlin_module")
    }

Save your changes to mainTemplate.gradle

AndroidManifest.xml

Take a look at file [Unity Project Folder]/Assets/Plugins/Android/AndroidManifest.xml

Before going to production, you will need to modify the following values. For now, you can use what's already there.

    <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" />

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

Ready to Build Android

At this point, you should be able to build Android. If you encounter the following dialogs, hit 'YES'.

OR

Freestar Initialization and Displaying Ads

Take a look at Assets/FreestarMediation/SampleFreestarAds.cs which was imported into your Unity project.

This working sample shows how to initialize, implement the ad listeners, and show banner, fullscreen Interstitial and Rewarded ads.
Assets/FreestarMediation/SampleFreestar.scene is also included.

Some publishers like to create a singleton class based on this sample. Utilize it as you see fit.

You can use the test key in SampleFreestarAds.cs

Privacy - Google Play Families Policy Compliance

If your game or app is officially under the Google Play Families program, Freestar provides such support:

FreeStarAds.setGoogleFamilyPolicyMode( GoogleFamilyPolicyMode.app, true); //If your app is designed only for children
//FreeStarAds.setGoogleFamilyPolicyMode( GoogleFamilyPolicyMode.mixed, false);  //If your app is designed for families with children
FreeStarAds.init(...);

If your app is not officially under the Google Play Families program, then you do not need to set the Google Family Policy mode.

    /**
     * Only set Google Families Policy Mode if your app is required to comply with Google Play’s
     * Families Policy program.
     *
     * @param googleFamilyPolicyMode app: the app is child-directed and will not receive
     *                               personalize or contextual ads.
     *                               mixed: the app is directed at mixed audiences.
     *                               none: (default) the app is not required to comply with Google
     *                                      Play's Family Policy
     *
     * @param onlyNonPersonalizedAds true: if 'mixed' mode, then only personalized or contextual ads
     *                                     may be served.
     *                               false: if 'mixed' mode, then personalized or contextual ads
     *                                      may be served.
     *                               note:  if 'app' mode, then personalized or contextual ads
     *                                      may not be served regardless of this parameter.
     */
    public static void setGoogleFamilyPolicyMode(GoogleFamilyPolicyMode googleFamilyPolicyMode,
                                                 boolean onlyNonPersonalizedAds)

GDPR

Freestar SDK is GDPR compliant. In order for your users to be able to receive any ad fills in GDPR-affected countries, you, as a publisher, will need to implement a 3rd party Consent Management Platform (CMP). Freestar SDK will automatically detect user interactions with the CMP and act accordingly. Please see our Freestar GDPR Frequently Asked Questions for complete details and our recommended list of CMP service providers.

Testing

For Android, please use our test key XqjhRR for all your testing runs and enable test mode true. You will usually get 100% fill on all ad units. It is not recommended to use your production key for testing runs as that is strictly prohibited by our partners and bad things may happen to us on the business side of things.
Do not forget to uninstall and re-install your app when changing keys on your device.

When you are satisfied with your testing, please make a release build with your production key, and turn test mode off. Publish to store.

Automated Testing - Bypassing Ads

Are your automated tests failing after integrating Freestar Mediation Ads into your mobile application or game? Are you not sure it could be due to Freestar or something else? We have a feature called Automated Test Mode where you can run your automated tests to bypass Freestar or run Freestar in 'Limited Mediation' mode without making drastic changes to your code:

In your automated test suite code, before FreeStarAds.init is called:

FreeStarAds.setAutomatedTestMode( FreeStarAds.AutomatedTestMode.BYPASS_ALL_ADS )  
  //OR
FreeStarAds.setAutomatedTestMode( FreeStarAds.AutomatedTestMode.LIMITED_MEDIATION )    //only runs AdMob & GAM

Again, this is only for your automated tests and not for production use.

Release Build

Final note when creating your release build: if you use proguard or minify, please add our proguard rules to your app proguard file.

Freestar Ads Mediation provides support for React Native

Getting Started

Start displaying Freestar Ads in your existing React Native app running on Android today by following the simple steps below.

Requirements

• Before we begin, you must have a working React Native app running on an Android device. This document will not show how to create a React Native app running under Android as that would be beyond the scope of Freestar Ads Mediation.

• Make sure you have the latest version of Android Studio.

Modify Android Project

Open the Android native build project using Android Studio. It is located in [your react project]/android folder.

Follow the Native Android Project Setup Guide here, which is modification of the build.gradle and AndroidManifest.xml

After making the changes to build.gradle and AndroidManifest.xml, return here. It should not take very long. Make sure you uncommented the following line in your app/build.gradle:

implementation 'com.freestar.android.ads:react-native-android:1.1.1'

Remove Old Java Files

In our older integration documentation, there were 3 java source files:

 
FreestarReactPackage.java
FreestarReactBridge.java
FreestarBannerAdViewManager.java

Please remove these as they are now located within the dependency:

implementation 'com.freestar.android.ads:react-native-android:1.1.1'

Install our npm package

In your React Native project root folder, install our Freestar npm package:

npm install --save @freestar/freestar-plugin-react-native
(the latest npm package version is 1.2.3)

NOTE: if you already have the plugin installed, you should update it:

npm update --save @freestar/freestar-plugin-react-native

Modify MainApplication.java

In Android Studio, open MainApplication.java

In the getPackages() method, add our FreestarReactPackage:

It should look something similar to this:

    @Override
    protected List getPackages() {
      List packages = new PackageList(this).getPackages();
      packages.add(new ModuleRegistryAdapter(mModuleRegistryProvider));
      packages.add(new com.freestar.android.ads.react.FreestarReactPackage());  //This is the only Freestar line in this file
      return packages;
    }

Modify MainActivity.java

In Android Studio, open MainActivity.java

In the onCreate method of MainActivity.java initialize Freestar. It should look something like this:

//Put these import statements at the top
import com.freestar.android.ads.AdRequest;
import com.freestar.android.ads.FreeStarAds;  

  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    //Freestar begin

    /**
     * Note: When the enable-test-ads flag is set to [true], there will be a dialog prompt to choose 
     * mediation partners.  Set to [false] to remove that dialog and when getting ready to release
     * to production.
     * 
    */
    FreeStarAds.enableTestAds(true); //set false for production
    FreeStarAds.enableLogging(true); //set false for production
    AdRequest adRequest = new AdRequest(this);
    adRequest.addCustomTargeting("someParam1", "someValue1"); //optional targeting param for pre-fetched ads
    adRequest.addCustomTargeting("someParam2", "someValue2"); //optional targeting param for pre-fetched ads

    //Uncomment the following line if you wish to utilize App Open Ads in your Android app
    //FreeStarAds.requestAppOpenAds("app-open-ad-placement", true, null);   

    FreeStarAds.init(this, "XqjhRR", adRequest);  //Use our test key "XqjhRR" for all testing runs

    //The following init also works if you don't use custom targeting 
    //FreeStarAds.init(this, "XqjhRR");

    //Freestar end
  }

Displaying Ads

The final piece to the puzzle is displaying ads in React Native js code.

In your application js, make sure to import our Freestar React plugin:

import FreestarReactBridge from '@freestar/freestar-plugin-react-native';
import BannerAd from '@freestar/freestar-plugin-react-native/BannerAd';
import MrecBannerAd from '@freestar/freestar-plugin-react-native/MrecBannerAd';
import SmallNativeAd from '@freestar/freestar-plugin-react-native/SmallNativeAd';
import MediumNativeAd from '@freestar/freestar-plugin-react-native/MediumNativeAd';

App Open Ads

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 Android app, call the following method before FreeStarAds.init in MainActivity.java:

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

Fullscreen Interstitial Ads

We start by subscribing to the Interstitial callbacks:

FreestarReactBridge.subscribeToInterstitialCallbacks((eventName, placement) => {
       if(eventName === "onInterstitialLoaded") {

         if (placement == 'not defined') {  //Important: Check if the placement comes in as the literal 'not defined'
             placement = null;
         }
         FreestarReactBridge.showInterstitialAd(placement);  //placement cannot be empty string '', but can be null or any string.

       } else if (eventName === "onInterstitialClicked") {

       } else if (eventName === "onInterstitialShown") {

       } else if (eventName === "onInterstitialFailed") {

           Alert.alert('Interstitial Ad not available');

       } else if (eventName === "onInterstitialDismissed") {

       } else {
          console.log("unknown event");
       }
     });

To load an interstitial ad:

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.

//In this case, we use the default placement, so we pass null for the placement name.
FreestarReactBridge.loadInterstitialAd(null);

Fullscreen Rewarded Ads

We start by subscribing to the Rewarded callbacks:

FreestarReactBridge.subscribeToRewardCallbacks((eventName, placement, rewardName = '', rewardAmount = 0) => {
     if (eventName === "onRewardedFailed") {

          Alert.alert('Reward Ad not available');

     } else if (eventName === "onRewardedDismissed") {

     } else if(eventName === "onRewardedLoaded") {

         if (placement == 'not defined') {  //Important: Check if the placement comes in as the literal 'not defined'
             placement = null;  
         }
         //placement cannot be empty string '', but can be null or any string.
         FreestarReactBridge.showRewardAd(placement, "Coins", 50, "myuserId", "12345678");

     } else if (eventName === "onRewardedCompleted") {

         console.log("reward ad completed: awarded " + rewardAmount + ' ' + rewardName);

     } else if (eventName === "onRewardedShown") {

     } else if (eventName === "onRewardedShowFailed") {

          Alert.alert('Reward Ad was available but failed to show');

     } else {
        console.log("unknown event");
     }
   });

To load a Rewarded ad:

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.

//In this case, we use the default placement, so we pass null for the placement name.
FreestarReactBridge.loadRewardAd(null);

Small Banner Ad 320x50

      <BannerAd
         style={{width: 320, height: 50}}    //Do not use other values besides 320 and 50 for small banner
         requestOptions={
            {
               size: 'BANNER',
               //placement: 'home_page_p1' //NOTE: if this placement has not been setup in the back-end, then do NOT specify placement
               targetingParams: {
                     'someparam1': 'somevalue1',
                     'someparam2': 'somevalue2',
                     'someparam3': 'somevalue3',
               },
               testDeviceIds: ['deviceId1','deviceId2', 'deviceId3']
            }
         }
         onBannerAdLoaded={someBannerLoadedHandler}
         onBannerAdFailedToLoad={someBannerFailedHandler}
      />

Medium Rectangle Banner Ad 300x250 - MREC

      <BannerAd
         style={{width: 300, height: 250}}    //Do not use other values besides 300 and 250 for mrec banner
         requestOptions={
            {  
               size: 'MREC',
               //placement: 'home_page_p1' //NOTE: if this placement has not been setup in the back-end, then do NOT specify placement
               targetingParams: {
                     'someparam1': 'somevalue1',
                     'someparam2': 'somevalue2',
                     'someparam3': 'somevalue3',
               },
               testDeviceIds: ['deviceId1','deviceId2', 'deviceId3']
            }
         }
         onBannerAdLoaded={someBannerLoadedHandler}
         onBannerAdFailedToLoad={someBannerFailedHandler}
      />

Another simple way to display MREC is as follows. Specify 'MrecBannerAd' and do not specify the 'size' in requestOptions.

      <MrecBannerAd
         style={{width: 300, height: 250}}    //Do not use other values besides 300 and 250 for mrec banner
         requestOptions={
            {
               //placement: 'home_page_p1' //NOTE: if this placement has not been setup in the back-end, then do NOT specify placement
               targetingParams: {
                     'someparam1': 'somevalue1',
                     'someparam2': 'somevalue2',
                     'someparam3': 'somevalue3',
               },
               testDeviceIds: ['deviceId1','deviceId2', 'deviceId3']
            }
         }
         onBannerAdLoaded={someBannerLoadedHandler}
         onBannerAdFailedToLoad={someBannerFailedHandler}
      />

Small Native Ad 360x100

      //Note: The ad width should actually be the full screen width.  360 (below) is for demonstration purposes.
      <SmallNativeAd
         style={{width: 360, height: 100}}
         requestOptions={
            {
               //placement: 'home_page_p1' //NOTE: if this placement has not been setup in the back-end, then do NOT specify placement
               targetingParams: {
                     'someparam1': 'somevalue1',
                     'someparam2': 'somevalue2',
                     'someparam3': 'somevalue3',
               },
               testDeviceIds: ['deviceId1','deviceId2', 'deviceId3']
            }
         }
         onNativeAdLoaded={someNativeLoadedHandler}
         onNativeAdFailedToLoad={someNativeFailedHandler}
      />

Medium Native Ad 360x350

      //Note: The ad width should actually be the full screen width.  360 (below) is for demonstration purposes.
      <MediumNativeAd
         style={{width: 360, height: 350}}
         requestOptions={
            {
               //placement: 'home_page_p1' //NOTE: if this placement has not been setup in the back-end, then do NOT specify placement
               targetingParams: {
                     'someparam1': 'somevalue1',
                     'someparam2': 'somevalue2',
                     'someparam3': 'somevalue3',
               },
               testDeviceIds: ['deviceId1','deviceId2', 'deviceId3']
            }
         }
         onNativeAdLoaded={someNativeLoadedHandler}
         onNativeAdFailedToLoad={someNativeFailedHandler}
      />

For more information on how to optionally customize the look and feel of the SmallNativeAd or MediumNativeAd please see our Android Native Ad Unit document.

Please have a look at our sample code to see how it all works: App.js

Privacy - Google Play Families Policy Compliance

If your game or app is officially under the Google Play Families program, Freestar provides such support:

FreeStarAds.setGoogleFamilyPolicyMode( GoogleFamilyPolicyMode.app, true); //If your app is designed only for children
//FreeStarAds.setGoogleFamilyPolicyMode( GoogleFamilyPolicyMode.mixed, false);  //If your app is designed for families with children
FreeStarAds.init(...);

If your app is not officially under the Google Play Families program, then you do not need to set the Google Family Policy mode.

    /**
     * Only set Google Families Policy Mode if your app is required to comply with Google Play’s
     * Families Policy program.
     *
     * @param googleFamilyPolicyMode app: the app is child-directed and will not receive
     *                               personalize or contextual ads.
     *                               mixed: the app is directed at mixed audiences.
     *                               none: (default) the app is not required to comply with Google
     *                                      Play's Family Policy
     *
     * @param onlyNonPersonalizedAds true: if 'mixed' mode, then only personalized or contextual ads
     *                                     may be served.
     *                               false: if 'mixed' mode, then personalized or contextual ads
     *                                      may be served.
     *                               note:  if 'app' mode, then personalized or contextual ads
     *                                      may not be served regardless of this parameter.
     */
    public static void setGoogleFamilyPolicyMode(GoogleFamilyPolicyMode googleFamilyPolicyMode,
                                                 boolean onlyNonPersonalizedAds)

GDPR

Freestar SDK is GDPR compliant. In order for your users to be able to receive any ad fills in GDPR-affected countries, you, as a publisher, will need to implement a 3rd party Consent Management Platform (CMP). Freestar SDK will automatically detect user interactions with the CMP and act accordingly. Please see our Freestar GDPR Frequently Asked Questions for complete details and our recommended list of CMP service providers.

Testing

For Android, please use our test key XqjhRR for all your testing runs and enable test mode true. You will usually get 100% fill on all ad units. It is not recommended to use your production key for testing runs as that is strictly prohibited by our partners and bad things may happen to us on the business side of things.
Do not forget to uninstall and re-install your app when changing keys on your device.

When you are satisfied with your testing, please make a release build with your production key, and turn test mode off. Publish to store.

Automated Testing - Bypassing Ads

Are your automated tests failing after integrating Freestar Mediation Ads into your mobile application or game? Are you not sure it could be due to Freestar or something else? We have a feature called Automated Test Mode where you can run your automated tests to bypass Freestar or run Freestar in 'Limited Mediation' mode without making drastic changes to your code:

In your automated test suite code, before FreeStarAds.init is called:

FreeStarAds.setAutomatedTestMode( FreeStarAds.AutomatedTestMode.BYPASS_ALL_ADS )  
  //OR
FreeStarAds.setAutomatedTestMode( FreeStarAds.AutomatedTestMode.LIMITED_MEDIATION )    //only runs AdMob & GAM

Again, this is only for your automated tests and not for production use.

Release Build

Final note when creating your release build: if you use proguard or minify, please add our proguard rules to your app proguard file.

Freestar Ads Mediation provides support for Cordova

Getting Started

Maximize your revenue and start displaying Freestar Mediation Ads in your existing Cordova mobile app running on Android today.

Requirements

• Before we begin, you must have a working Cordova app running on an Android device.

• Make sure you have the latest version of Android Studio.

Install our npm package

In your Cordova project root folder:

cordova plugin add @freestar/cordova-plugin-freestar

Once installed or updated, please make sure cordova-plugin-freestar is at least version 1.2.0 by looking within your package.json file.

If for any reason the old cordova-plugin-freestar does not get added/updated, try removing the existing plugin before adding:

cordova plugin remove cordova-plugin-freestar

You can also try to update:

cordova plugin update @freestar/cordova-plugin-freestar

config.xml

Add the following to config.xml in your project root folder:

<preference name="AndroidXEnabled" value="true" />

AndroidManifest.xml

Add the following to [Cordova project root]/platforms/android/app/src/main/AndroidManifest.xml to the application tag:

        <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" />
        <meta-data
            android:name="com.freestar.android.ads.API_KEY"
            android:value="XqjhRR" />

Important Note: The above are test values that will need to be changed before releasing to production.

Banner Ads

   
/*  USAGE: window.plugins.freestarPlugin.showBannerAd(placement, bannerAdSize, bannerAdPosition)
 *
 *  1st parameter is the placement. Please pass null
 *  if you aren't using one or the string placement.
 *
 *  2nd parameter can be ONE of the following:
 *  window.plugins.freestarPlugin.BANNER_AD_SIZE_320x50
 *  window.plugins.freestarPlugin.BANNER_AD_SIZE_300x250
 *  window.plugins.freestarPlugin.BANNER_AD_SIZE_728x90
 * 
 *  3rd parameter can be ONE of the following:
 *  window.plugins.freestarPlugin.BANNER_AD_POSITION_BOTTOM
 *  window.plugins.freestarPlugin.BANNER_AD_POSITION_CENTER
 *  window.plugins.freestarPlugin.BANNER_AD_POSITION_TOP
 */
  
//EXAMPLE: Show a small banner ad at the bottom of the screen with default null placement:
window.plugins.freestarPlugin.showBannerAd(null,
                                           window.plugins.freestarPlugin.BANNER_AD_SIZE_320x50,
                                           window.plugins.freestarPlugin.BANNER_AD_POSITION_BOTTOM);

//To close the banner ad:
window.plugins.freestarPlugin.closeBannerAd(placement, bannerAdSize);  //Closes the banner ad

//Register for the following banner ad callbacks and define their functions:
document.addEventListener('onBannerAdShowing', onBannerAdShowing, false);
document.addEventListener('onBannerAdFailed', onBannerAdFailed, false);
document.addEventListener('onBannerAdClicked', onBannerAdClicked, false);

function onBannerAdShowing(data) {
   console.log('banner showing. placement: ' + data.placement 
                            + ' bannerAdSize: ' + data.banner_ad_size);
}

function onBannerAdFailed(data) {
   console.log('banner show failed. placement: ' + data.placement 
                                 + ' bannerAdSize: ' + data.banner_ad_size 
                                 + ' error: ' + data.error);
}

function onBannerAdClicked(data) {
   console.log('banner clicked. placement: ' + data.placement 
                            + ' bannerAdSize: ' + data.banner_ad_size);
}

Interstitial Ads

//Register for the following interstitial callbacks and declare/define their functions:
document.addEventListener('onInterstitialLoaded', onInterstitialLoaded, false);
document.addEventListener('onInterstitialFailed', onInterstitialFailed, false);
document.addEventListener('onInterstitialShown', onInterstitialShown, false);
document.addEventListener('onInterstitialDismissed', onInterstitialDismissed, false);
document.addEventListener('onInterstitialClicked', onInterstitialClicked, false);

//Load the interstitial ad.  Pass in the string placement, or null if you don't use one.
window.plugins.freestarPlugin.loadInterstitialAd(null);

//Declare the following function and show the interstitial ad within it.
function onInterstitialLoaded(data) {
   console.log("onInterstitialLoaded: "+ data.placement);

   //Don't forget to pass in the placement
   window.plugins.freestarPlugin.showInterstitialAd(data.placement);
}

function onInterstitialFailed(data) {
   console.log("onInterstitialFailed: "+ data.placement + " " + data.error);

   //Note: It is not recommended to call loadInterstitialAd here as it can cause eternal loop.
}

function onInterstitialShown(data) {
   console.log("onInterstitialShown: "+ data.placement);
}

function onInterstitialDismissed(data) {
   console.log("onInterstitialDismissed: "+ data.placement);
   
   //Note: It is not recommended to pre-fetch the next ad in here because we already do that internally.
}

function onInterstitialClicked(data) {
   console.log("onInterstitialClicked: "+ data.placement);
}

Rewarded Ads

//Register for the following rewarded ad callbacks and declare/define their functions:

document.addEventListener('onRewardedVideoLoaded', onRewardedVideoLoaded, false);
document.addEventListener('onRewardedVideoFailed', onRewardedVideoFailed, false);
document.addEventListener('onRewardedVideoShown', onRewardedVideoShown, false);
document.addEventListener('onRewardedVideoShownError', onRewardedVideoShownError, false);
document.addEventListener('onRewardedVideoDismissed', onRewardedVideoDismissed, false);
document.addEventListener('onRewardedVideoCompleted', onRewardedVideoCompleted, false);

//Load the rewarded ad.  Pass in the string placement, or null if you don't use one.
window.plugins.freestarPlugin.loadRewardedAd(null);

//Declare the following function and show the rewarded ad within it.
function onRewardedVideoLoaded(data) {
   console.log("onRewardedVideoLoaded: "+ data.placement);
   //MySecret123 - optional, can be any string
   //MyUserId - optional, can be any string
   //Gold Coins - optional, type of reward, can be any string like 'V-Bucks', 'Gold Coins', etc
   //100 - optional, string value representing the amount of type of reward
   //don't forget to pass the placement to show.
   window.plugins.freestarPlugin.showRewardedAd(data.placement, "MySecret123", "MyUserId", "Gold Coins", "100");
}

//Define the rest of the rewarded ad callbacks:

function onRewardedVideoFailed(data) {
   console.log("onRewardedVideoFailed: "+ data.placement + " " + data.error);

   //Note: It is not recommended to call loadRewardedAd here as it can cause eternal loop.
}

function onRewardedVideoShown(data) {
   console.log("onRewardedVideoShown: "+ data.placement);
}

function onRewardedVideoShownError(data) {
   console.log("onRewardedVideoShownError: "+ data.placement + " " + data.error);
}

function onRewardedVideoDismissed(data) {
   console.log("onRewardedVideoDismissed: "+ data.placement);
   
   //Note: It is not recommended to pre-fetch the next ad in here because we already do that internally.
}

function onRewardedVideoCompleted(data) {
   console.log("onRewardedVideoCompleted: "+ data.placement);
   //This callback means the user has completed watching the video and you may reward them at this time.

   //Note: It is not recommended to pre-fetch the next ad in here because we already do that internally.
}

Toggle Test Mode

You can toggle between test and production mode. Pass false or omit the following line to turn off test mode.

window.plugins.freestarPlugin.setTestModeEnabled( true|false );

Sample Cordova App

Check out our Cordova sample.

Privacy - Google Play Families Policy Compliance

If your game or app is officially under the Google Play Families program, Freestar provides such support:

FreeStarAds.setGoogleFamilyPolicyMode( GoogleFamilyPolicyMode.app, true); //If your app is designed only for children
//FreeStarAds.setGoogleFamilyPolicyMode( GoogleFamilyPolicyMode.mixed, false);  //If your app is designed for families with children
FreeStarAds.init(...);

If your app is not officially under the Google Play Families program, then you do not need to set the Google Family Policy mode.

    /**
     * Only set Google Families Policy Mode if your app is required to comply with Google Play’s
     * Families Policy program.
     *
     * @param googleFamilyPolicyMode app: the app is child-directed and will not receive
     *                               personalize or contextual ads.
     *                               mixed: the app is directed at mixed audiences.
     *                               none: (default) the app is not required to comply with Google
     *                                      Play's Family Policy
     *
     * @param onlyNonPersonalizedAds true: if 'mixed' mode, then only personalized or contextual ads
     *                                     may be served.
     *                               false: if 'mixed' mode, then personalized or contextual ads
     *                                      may be served.
     *                               note:  if 'app' mode, then personalized or contextual ads
     *                                      may not be served regardless of this parameter.
     */
    public static void setGoogleFamilyPolicyMode(GoogleFamilyPolicyMode googleFamilyPolicyMode,
                                                 boolean onlyNonPersonalizedAds)

GDPR

Freestar SDK is GDPR compliant. In order for your users to be able to receive any ad fills in GDPR-affected countries, you, as a publisher, will need to implement a 3rd party Consent Management Platform (CMP). Freestar SDK will automatically detect user interactions with the CMP and act accordingly. Please see our Freestar GDPR Frequently Asked Questions for complete details and our recommended list of CMP service providers.

Testing

For Android, please use our test key XqjhRR for all your testing runs and enable test mode true. You will usually get 100% fill on all ad units. It is not recommended to use your production key for testing runs as that is strictly prohibited by our partners and bad things may happen to us on the business side of things.
Do not forget to uninstall and re-install your app when changing keys on your device.

When you are satisfied with your testing, please make a release build with your production key, and turn test mode off. Publish to store.

Automated Testing - Bypassing Ads

Are your automated tests failing after integrating Freestar Mediation Ads into your mobile application or game? Are you not sure it could be due to Freestar or something else? We have a feature called Automated Test Mode where you can run your automated tests to bypass Freestar or run Freestar in 'Limited Mediation' mode without making drastic changes to your code:

In your automated test suite code, before FreeStarAds.init is called:

FreeStarAds.setAutomatedTestMode( FreeStarAds.AutomatedTestMode.BYPASS_ALL_ADS )  
  //OR
FreeStarAds.setAutomatedTestMode( FreeStarAds.AutomatedTestMode.LIMITED_MEDIATION )    //only runs AdMob & GAM

Again, this is only for your automated tests and not for production use.

Release Build

Final note when creating your release build: if you use proguard or minify, please add our proguard rules to your app proguard file.

Freestar Ads Mediation provides support for Xamarin Android in C# by providing the necessary NuGet packages.

Supported Ad Partners

Note: The supported list for Xamarin may differ from our Native Android

Getting Started

Start displaying Freestar Ads in your Xamarin app today by following the simple steps below.

Requirements

• Before we begin, you must have a working Xamarin app running on an Android device. This document will not show how to create a Xamarin app for Android as that would be beyond the scope of Freestar Ads Mediation.

• Your Xamarin app must target MonoAndroid 9.0 or higher.

NuGet Dependencies

In Visual Studio, INSTALL the following NuGet packages:

AndroidManifest.xml

Please add the following meta-data tags to the Application tag of the AndroidManifest.xml Note: The Google and AppLovin values below are non-production values.

    <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="qwFfGU-34yfW7sQ0boTdLe5GOlb6TG1HAHxRnwUrs8M--o-aZSCv5IAT1naV1bnCuidec6UTFsSEdRqCv15_JG" />

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

Freestar Initialization

In the onCreate of your starting Activity:

FreeStarAds.EnableTestAds(true);  //set 'false' for production
FreeStarAds.Init( [YOUR PARENT ACTIVITY], "XqjhRR"); //Use our test key

Interstitial Ads

How to display full screen Interstitial ads:

First, implement the IInterstitialAdListener interface.

Note: How to implement an interface in C# is beyond the scope of this document.

InterstitialAd interstitialAd = new InterstitialAd( [YOUR Parent Activity] , [YOUR IInterstitialAdListener] );

AdRequest adRequest = new AdRequest( [YOUR Parent Activity] );

interstitialAd.LoadAd(adRequest);  //Note: you may pass an optional "placement" string as 2nd parameter if you wish.

When you receive OnInterstitialLoaded from your IInterstitialAdListener, you may show the ad:

interstitialAd.Show();

Rewarded Ads

How to display full screen Rewarded ads:

First, implement the IRewardedAdListener interface.

Note: How to implement an interface in C# is beyond the scope of this document.

RewardedAd rewardedAd = new RewardedAd ( [YOUR Parent Activity] , [YOUR IRewardedAdListener] );

AdRequest adRequest = new AdRequest( [YOUR Parent Activity] );

rewardedAd.LoadAd(adRequest);  //Note: you may pass an optional "placement" string as 2nd parameter if you wish.

When you receive OnRewardedVideoLoaded from your IRewardedAdListener, you may show the ad:

/*
  Secret:  Any arbitrary string you want to identify the reward by. e.g. "12345678".  Cannot be blank.
  User Name:  Can be the username of the user trying to obtain the reward; may be blank or null.
  Coin:  The name of the type of reward. e.g. gold coin;  may be blank or null.
  30:  The amount of the reward in string.  may be blank or null.
*/
rewardedAd.ShowRewardAd("mysecret", "MyUsername", "Gold Coins", "30");

Banner Ads

How to display Banner ads:

AdRequest adRequest = new AdRequest( [YOUR Parent Activity] );
BannerAd bannerAd = new BannerAd( [YOUR PARENT ACTIVITY] );
bannerAd.AdSize = AdSize.Banner32050;  //For MREC size, use AdSize.MediumRectangle300250
bannerAd.SetBannerAdListener( [YOUR IBannerAdListener] );
bannerAd.LoadAd(adRequest); //Note: you may pass an optional "placement" string as 2nd parameter if you wish.

Next, you will receive OnBannerAdLoaded of your IBannerAdListener. Here is an example implementation:

public void OnBannerAdLoaded(View bannerAdView, string placement)
{
    BannerAd ad = (BannerAd)bannerAdView;
    if (ad.AdSize == AdSize.Banner32050)
    {
        YOUR_AdContainer.RemoveAllViews();
        YOUR_AdContainer.AddView(bannerAdView); //FreeStar ad will be displayed now
    }
}

Sample Reference App

Please see the Xamarin_Android_Sample subfolder under this repo

Open using Microsoft Visual Studio

Privacy - Google Play Families Policy Compliance

If your game or app is officially under the Google Play Families program, Freestar provides such support:

FreeStarAds.setGoogleFamilyPolicyMode( GoogleFamilyPolicyMode.app, true); //If your app is designed only for children
//FreeStarAds.setGoogleFamilyPolicyMode( GoogleFamilyPolicyMode.mixed, false);  //If your app is designed for families with children
FreeStarAds.init(...);

If your app is not officially under the Google Play Families program, then you do not need to set the Google Family Policy mode.

    /**
     * Only set Google Families Policy Mode if your app is required to comply with Google Play’s
     * Families Policy program.
     *
     * @param googleFamilyPolicyMode app: the app is child-directed and will not receive
     *                               personalize or contextual ads.
     *                               mixed: the app is directed at mixed audiences.
     *                               none: (default) the app is not required to comply with Google
     *                                      Play's Family Policy
     *
     * @param onlyNonPersonalizedAds true: if 'mixed' mode, then only personalized or contextual ads
     *                                     may be served.
     *                               false: if 'mixed' mode, then personalized or contextual ads
     *                                      may be served.
     *                               note:  if 'app' mode, then personalized or contextual ads
     *                                      may not be served regardless of this parameter.
     */
    public static void setGoogleFamilyPolicyMode(GoogleFamilyPolicyMode googleFamilyPolicyMode,
                                                 boolean onlyNonPersonalizedAds)

GDPR

Freestar SDK is GDPR compliant. In order for your users to be able to receive any ad fills in GDPR-affected countries, you, as a publisher, will need to implement a 3rd party Consent Management Platform (CMP). Freestar SDK will automatically detect user interactions with the CMP and act accordingly. Please see our Freestar GDPR Frequently Asked Questions for complete details and our recommended list of CMP service providers.

Testing

For Android, please use our test key XqjhRR for all your testing runs and enable test mode true. You will usually get 100% fill on all ad units. It is not recommended to use your production key for testing runs as that is strictly prohibited by our partners and bad things may happen to us on the business side of things.
Do not forget to uninstall and re-install your app when changing keys on your device.

When you are satisfied with your testing, please make a release build with your production key, and turn test mode off. Publish to store.

Automated Testing - Bypassing Ads

Are your automated tests failing after integrating Freestar Mediation Ads into your mobile application or game? Are you not sure it could be due to Freestar or something else? We have a feature called Automated Test Mode where you can run your automated tests to bypass Freestar or run Freestar in 'Limited Mediation' mode without making drastic changes to your code:

In your automated test suite code, before FreeStarAds.init is called:

FreeStarAds.setAutomatedTestMode( FreeStarAds.AutomatedTestMode.BYPASS_ALL_ADS )  
  //OR
FreeStarAds.setAutomatedTestMode( FreeStarAds.AutomatedTestMode.LIMITED_MEDIATION )    //only runs AdMob & GAM

Again, this is only for your automated tests and not for production use.

Release Build

Final note when creating your release build: if you use proguard or minify, please add our proguard rules to your app proguard file.