Freestar Ads Mediation React Native Android

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.