Freestar Ads Mediation for Cordova Android

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.