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 ReactNative iOS app quickly and easily. This repo is a fully integrated ReactNative iOS sample app. Feel free to clone it, install the appropriate Cocoapods, launch ReactNative 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.

See SDK Version and Supported Demand Source Partner Versions

The ReactNative environment generates an Xcode project on creation, including a companion Pods project to install appropriate dependencies via Cocoapods. To integrate the Freestar SDK, install the ReactNative plugin from npm (latest version 1.3.6):

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

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

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

Then edit the Podfile:

1. ReactNative generates a project with the minimum iOS target version of 9.0. FreestarAds mimum requirement is 10.0, and the Podfile needs to reflect that:

platform :ios, '11.0' # minimum ios version

2. You need to specify the partners for which you want to run ads via Freestar mediation. Append them to the React-generated Podfile:

# M1 compatible
pod "FreestarAds-AdColony", "~> 4.7.2.1"
pod "FreestarAds-Tapjoy", "~> 12.8.0.1"
pod "FreestarAds-Criteo", "~> 4.3.1.1"
pod "FreestarAds-AppLovin", "~> 11.0.0.1"
pod "FreestarAds-AppLovinMax", "~> 11.0.0.2"
pod "FreestarAds-Hyprmx", "~> 6.0.3.4"
pod "FreestarAds-Yahoo", "~> 1.14.2.2"
pod "FreestarAds-Ogury", "~> 2.1.0.3"
pod 'FreestarAds-Googleadmob', '~> 10.0.0.6'
pod 'FreestarAds-Googleadmob/Facebook', '~> 10.0.0.6'
pod 'FreestarAds-GAM', '~> 10.0.0.6'
pod 'FreestarAds-GAM/Facebook', '~> 10.0.0.6'
pod "FreestarAds-Unity", "~> 4.1.0.4"
pod "FreestarAds-Prebid", "~> 2.1.2.10"
pod "FreestarAds-TAM", "~> 4.6.0.6"
pod "FreestarAds-Fyber2", "~> 8.1.6.1"
pod "FreestarAds-Nimbus", "~> 2.1.2.4"
pod "FreestarAds-Smaato", "~> 22.1.3.1"

# Not M1 compatible pods
pod "FreestarAds-Vungle", "~> 6.10.6.2"
pod "FreestarAds-Google", "~> 3.13.0.1"
pod "FreestarAds-Pangle", "~> 3.7.0.1"

NOTE: The FreestarAds Core version is '5.26.0'. Rerun pod install in the ios directory of the ReactNative project. Then open the generated .xcworkspace project with Xcode.

Some ad networks require adding special parameters in the app's Info.plist file. Below are the partner-specific Info.plist requirements.

<key>GADIsAdManagerApp</key>
<true/>

<key>GADApplicationIdentifier</key>
<string>{YOUR_ADMOB_KEY}</string>

<key>AppLovinSdkKey</key>
<string>{YOUR_APPLOVIN_KEY}</string>

<key>NSCalendarsUsageDescription</key>
<string>Adding events</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Taking selfies</string>
<key>NSCameraUsageDescription</key>
<string>Taking selfies</string>
<key>NSMotionUsageDescription </key>
<string>Interactive ad controls</string>

In the above entry, you should change the reasons to be appropriate for your app.

You can enable detailed logging from the SDK to inspect the ad mediation process in detail via an app's console. This is done by setting a flag in the Info.plist file:

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

Once this change is made, rebuild the app to see the logs.

❗⚠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.

To interface with the Freestar ad mediation, have the following at the top of the code file where you want to make use of the SDK:

import FreestarReactBridge from 'freestar-plugin-react';

import FreestarReactBridge from "@freestar/freestar-plugin-react-native";

Freestar is GDPR-ready and supports the IAB Standards for GDPR compliance.

Use the following simple api in conjunction with your existing Consent Management Provider. If you do not have a CMP solution, that’s ok, too! Our mediation sdk will detect if the user is in the EU and automatically apply GDPR actions to the ad request. So, by default, you do not have to do any extra work to use our sdk in a GDPR-compliant fashion.

// Save GDPR consent string
FreestarReactBridge.subjectToGDPR( 
    gdprApplies,      //boolean
    gdprConsentString //string
);

Freestar must be initialized as close as possible to the app launch. This gives the prefetch mechanism time work and thus, makes ad fill more likely when a request is made.

export default function App(props) {
    let FREESTAR_API_KEY = "P8RIA3";
    FreestarReactBridge. initWithAdUnitID(FREESTAR_API_KEY);

    //more initialization code

    return (
        //overall react UI
    );
}

Provide the SDK with the callback function for events related to interstitial ads:

FreestarReactBridge.subscribeToInterstitialCallbacks((eventName) => {
    if(eventName === "onInterstitialLoaded") {
        // ad can now be shown
    } else if (eventName === "onInterstitialClicked") {
        // ad clicked
    } else if (eventName === "onInterstitialShown") {
        // ad shown
    } else if (eventName === "onInterstitialFailed") {
        // no ad available
    } else if (eventName === "onInterstitialDismissed") {
        //ad has closed, resume the app
    } else {
       console.log("unknown event");
    }
  });

This allows your app to listen to ad events and act appropriately. In the current sample app, this is implemented in the FullscreenAds() function of the App.js file.

To receive any callbacks, you will need to load the ad:

//You can load associated to a placement as follows, or pass in
// the empty string for the default placement
FreestarReactBridge.loadInterstitialAd("interstitial_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 specify a placement name by calling the loadInterstitialAd() method with "" as the argument. 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 placement format 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 event will arrive.

FreestarReactBridge.subscribeToInterstitialCallbacks((eventName) => {
    if(eventName === "onInterstitialLoaded") {
        // ad can now be shown
        //You can display the ad now OR show it later; your choice.
        FreestarReactBridge.showInterstitialAd();
    }
    //other events
}

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 App.js on this sample for those details.

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

FreeStar supports 300x250 (MREC) and 320x50 (BANNER) banner ad formats and allows you to control the refresh intervals remotely. You can use ReactNative to place the ads in appropriate locations in your app.

To do so, first, import the banner ad objects from the plugin:

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

MrecBannerAd comes in separate classes to enable displaying the MREC-size ad. The same setup applies to the Small and Medium native ad units (see below): 4 distinct options for each.

Then setup the ad:

    <BannerAd
        style={{width: 320, height: 50}}
        requestOptions={{ size:'BANNER' }}
        onBannerAdLoaded={bannerLoaded}
        onBannerAdFailedToLoad={bannerFailed}
      />

And for MREC:

<View style={{ flexDirection: 'row', paddingTop: 10}}>
  < MrecBannerAd
      style={{width: 300, height: 250}}
      requestOptions={
        {
            size:'MREC',
            isCoppaEnabled: false,
            targetingParams: {
                  'someparam1': 'somevalue1',
                  'someparam2': 'somevalue2',
                  'someparam3': 'somevalue3',
            },
            testDeviceIds: ['deviceId1','deviceId2', 'deviceId3']
        }
      }
      onBannerAdLoaded={bannerLoaded}
      onBannerAdFailedToLoad={bannerFailed}
  />
</View>

The bannerLoaded and bannerFailed should be functions implemented by you to handle the corresponding events. The ad will load automatically after being inserted into the view hierarchy, and display when it is ready.

Note: the requestOptions parameter is required. If your app has no additional parameters to pass in, add requestOptions={{}} to the banner ad element.

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

< BannerAd
         style={{width: 320, height: 50}}
         requestOptions={
            {
               size:'BANNER',
               targetingParams: {
                     'someparam1': 'somevalue1',
                     'someparam2': 'somevalue2',
                     'someparam3': 'somevalue3'
               }
            }
         }
         onBannerAdLoaded={bannerLoaded}
        onBannerAdFailedToLoad={bannerFailed}
        />
< MrecBannerAd
         style={{width: 300, height: 250}}
         requestOptions={
            {
               size:'MREC',
               targetingParams: {
                     'someparam1': 'somevalue1',
                     'someparam2': 'somevalue2',
                     'someparam3': 'somevalue3'
               }
            }
         }
         onBannerAdLoaded={bannerLoaded}
        onBannerAdFailedToLoad={bannerFailed}
        />

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.

Provide the SDK with the callback function for events related to rewarded ads:

FreestarReactBridge.subscribeToRewardCallbacks((eventName, rewardName = '', rewardAmount = 0) => {
    if (eventName === "onRewardedFailed") {
      // no ad available
    } else if (eventName === "onRewardedDismissed") {
      // ad closed
    } else if(eventName === "onRewardedLoaded") {
      // ad ready
    } else if (eventName === "onRewardedCompleted") {
      // received reward
      console.log("reward ad completed: awarded " + rewardAmount + ' ' + rewardName);
    } else if (eventName === "onRewardedShown") {

    } else if (eventName === "onRewardedShowFailed") {
      // couldn't display ad
    } else {
       console.log("unknown event");
    }
  });

This allows your app to listen to ad events and act appropriately. In the current sample app, this is implemented in the FullscreenAds() function of the App.js file.

To receive any callbacks, you will need to load the ad:

//You can load associated to a placement as follows, or pass in
// the empty string for the default placement
FreestarReactBridge.loadRewardAd("rewarded_p1");

When the rewarded ad is ready, the "onRewardedLoaded callback event will arrive.

FreestarReactBridge.subscribeToRewardCallbacks((eventName, rewardName = '', rewardAmount = 0) => {
    if(eventName === "onRewardedLoaded") {
      // ad can now be shown
      //You can display the ad now OR show it later; your choice.
      FreestarReactBridge.showRewardAd(
          "Coins",   //reward name
          50,        //reward amount
          "myuserId",//user id 
          "12345678" //secret key
      );
    }
    //other callback events
});

When the user has fully watched the rewarded ad (or when the given ad partner determines sufficient watch time for the reward), the onRewardedCompleted callback event will arrive.

When the user has closed the rewarded ad, the onRewardedDismissed callback event will arrive.

If the user does not watch the rewarded ad thru to completion, onRewardedCompleted callback event will not arrive, but the onRewardedDismissed event always arrive 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 with the allotted hour.

Organizationally, native ads work similar to banner ads, but permit customization of how ad data is displayed. They are only supported by the following partners:

• Mopub (deprecated)
• Googleadmob
• GAM

To display native ads in a ReactNative app, first import the native ad objects from the plugin:

import SmallNativeAd from '@freestar/freestar-plugin-react-native/SmallNativeAd';
import MediumNativeAd2 from '@freestar/freestar-plugin-react-native/MediumNativeAd';

And then add them to the app at the appropriate location:

<View style={{ flexDirection: 'row', paddingTop: 30}}>
  <MediumNativeAd
      style={{width: 300, height: 250}}
      requestOptions={
        {
            targetingParams: {
                  'someparam1': 'somevalue1',
                  'someparam2': 'somevalue2',
                  'someparam3': 'somevalue3',
            },
            testDeviceIds: ['deviceId1','deviceId2', 'deviceId3']
        }
      }
      onNativeAdLoaded={nativeLoaded}
      onNativeAdFailedToLoad={nativeFailed}
  />
  </View>
  
  <View style={{ flexDirection: 'row', paddingTop: 10}}>
  <SmallNativeAd
    style={{width: 320, height: 50}}
    requestOptions={{}}
    onNativeAdLoaded={nativeLoaded}
    onNativeAdFailedToLoad={nativeFailed}
  />
</View>

Just like with banners, the nativeLoaded and nativeFailed should be functions implemented by you to handle the corresponding events, and the requestOptions parameter is required. If your app has no additional parameters to pass in, add requestOptions={{}} to the native ad element.

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

    FreestarReactBridge.loadThumbnailAd(state.placementID);

Subscribe to the Thumbnail Ad callbacks:

FreestarReactBridge.subscribeToThumbnailAdCallbacks((eventName) => {
    if(eventName === "onThumbnailAdLoaded") {
      state.thumbnailReady = true;
         /*
            'bottomLeft' or 'bottomRight' or 'topLeft' or 'topRight' are possible initial screen
             location values of the Thumbnail Ad.
         */
         FreestarReactBridge.showThumbnailAd(state.placementID, "TopRight", 0, 0);

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

    } else if (eventName === "onThumbnailAdShown") {
      state.isShowingThumbnail = true;
    } else if (eventName === "onThumbnailAdFailed") {
      Alert.alert('Thumbnail Ad not available');
      state.thumbnailReady = false;
      state.isShowingThumbnail = false;
      setCanShowThumbnail(enableShowThumbnail());
    } else if (eventName === "onThumbnailAdDismissed") {
      state.isShowingThumbnail = false;
      state.thumbnailReady = false;
      setCanShowThumbnail(enableShowThumbnail());
    } else {
       console.log("unknown Thumbnail event");
    }
});

https://github.com/freestarcapital/SDK_documentation_iOS/blob/master/FreestarReactNativeSample