Freestar Ads Mediation Cordova iOS

Freestar Ads Mediation - Cordova Integration Guide for iOS

Supported Ad Partners

Note: The supported list for Cordova may differ from our Native iOS

Ad Provider	SDK Version	Ad Unit Types
AdColony	4.7.2	Fullscreen Interstitial & Rewarded
AppLovin	11.0.0	Fullscreen Interstitial & Rewarded, Banner 320x50
AppLovinMax	11.0.0	Fullscreen Interstitial & Rewarded, Banner 300x250, Banner 320x50
Admob	9.2.0	Fullscreen Interstitial & Rewarded, Banner 300x250, Banner 320x50
Criteo	4.3.0	Fullscreen Interstitial & Rewarded, Banner 300x250, Banner 320x50
Google Ads Manager	9.2.0	Fullscreen Interstitial & Rewarded, Banner 300x250, Banner 320x50
Tapjoy	12.8.0	Fullscreen Rewarded
Unity Ads	4.1.0	Fullscreen Interstitial & Rewarded
Vungle	6.10.6	Fullscreen Interstitial & Rewarded
Nimbus	1.10.5	Fullscreen Interstitial & Rewarded, Banner 300x250, Banner 320x50
TAM (Amazon Publisher Services)	4.4.3	Fullscreen Interstitial & Rewarded, Banner 300x250, Banner 320x50
Pangle	3.7.0	Fullscreen Interstitial & Rewarded, Banner 300x250, Banner 320x50
Hyprmx	6.0.3	Fullscreen Interstitial & Rewarded, Banner 300x250, Banner 320x50
Yahoo	1.14.2	Fullscreen Interstitial, Banner 300x250, Banner 320x50
Ogury	2.1.0	Fullscreen Interstitial & Rewarded, Banner 300x250, Banner 320x50
Prebid	2.0.3	Banner 300x250, Banner 320x50

Getting Started

Apache Cordova is a metaplatform for developing mobile apps with Javascript. This document will instruct you how to deliver Freestar Ads in mobile apps built with Cordova. Start displaying Freestar Ads in your Cordova app today by following the simple steps below.

Requirements

• NPM 6 or newer

• Cordova 9 or newer

• iOS SDK with Xcode for iOS 11 or higher

• Cocoapods

Begin

Please follow the instructions in order.

Go to your cordova app directory in a terminal and add the Freestar Cordova plugin:

$ cordova plugin add @freestar/cordova-plugin-freestar

If you do not wish to integrate every advertising partner, edit the following section of the node_modules/cordova-plugin-freestar/plugin.xml file so that only the partners you wish to include are listed:

<pods use-frameworks="true">
                <pod name="FreestarAds" spec="~> 5.17" />
                <pod name="FreestarAds-AdColony" spec="~> 4.7" />
                <pod name="FreestarAds-AppLovin" spec="~> 11.0" />
                <pod name="FreestarAds-AppLovinMax" spec="~> 11.0" />
                <pod name="FreestarAds-Criteo" spec="~> 4.3" />  
                <pod name="FreestarAds-GAM" spec="~> 9.2" />
                <pod name="FreestarAds-GAM/Facebook" spec="~> 9.2" />
                <pod name="FreestarAds-Googleadmob" spec="~> 9.2" />
                <pod name="FreestarAds-Googleadmob/Facebook" spec="~> 9.2" />
                <pod name="FreestarAds-Hyprmx" spec="~> 6.0" />
                <pod name="FreestarAds-Nimbus" spec="~> 1.10" />
                <pod name="FreestarAds-Ogury" spec="~> 2.1" />
                <pod name="FreestarAds-Pangle" spec="~> 3.7" />
                <pod name="FreestarAds-Prebid" spec="~> 2.0" />
                <pod name="FreestarAds-TAM" spec="~> 4.4" />
                <pod name="FreestarAds-Tapjoy" spec="~> 12.8" />
                <pod name="FreestarAds-Unity" spec="~> 4.1" />
                <pod name="FreestarAds-Vungle" spec="~> 6.10" />
                <pod name="FreestarAds-Yahoo" spec="~> 1.14" />
            </pods>

Freestar Ads require an API key to deliver ads. Once you obtain the key, make sure it is added to the app's Info.plist file in the generated iOS app. You can either edit the plist directly after the app is generated, or modify the Cordova app's config.xml file:

<platform name="ios">
  <edit-config target="com.freestar.ios.ads.API_KEY" file="*-Info.plist" mode="merge">
    <string>YOUR_API_KEY</string>
  </edit-config>
</platform>

If, in the list of partners describes above, you've asked to include either FreestarAds-Googleadmob or FreestarAds-GAM pods, you will also need to modify the generated app's Info.plist file to include Google's ad API key:

<edit-config target="GADApplicationIdentifier" file="*-Info.plist" mode="merge">
    <string>YOUR_ADMOB_KEY</string>
</edit-config>

Once all the changes are made, you can generate the iOS app from your cordova codebase:

$ cordova platform add ios

Opening the .xcworkspace file in the generated project with Xcode will allow you to run the app on the iOS simulator or device.

Displaying Ads

If the Freestar Cordova plugin was succesfully integrated, its apis will be accessible via the window.plugins.freestarPlugin object.

Interstitial Ads

Interstitial ads take over the app, running in fullscreen, and allow return to the app upon completion. You can opt in to receive callbacks when key events occur in an ad's lifecycle, allowing you to make any changes necessary (such as pausing your game while the ad is playing). To do this, your Cordova code needs to add event listeners to the corresponding ad events:

document.addEventListener('onInterstitialLoaded', onInterstitialLoaded, false);
document.addEventListener('onInterstitialFailed', onInterstitialFailed, false);
document.addEventListener('onInterstitialShown', onInterstitialShown, false);
document.addEventListener('onInterstitialClicked', onInterstitialClicked, false);
document.addEventListener('onInterstitialDismissed', onInterstitialDismissed, false);

Then, you request to load an ad:

window.plugins.freestarPlugin.loadInterstitialAd(AD_PLACEMENT);

Note: there are additional details of what placements are and the format they need to be in our guide for native app integration. If you do not wish to use placements, simply pass in null:

window.plugins.freestarPlugin.loadInterstitialAd(null);

While implementing callbacks is optional, showing an ad before it's loaded will not work. The onInterstitialAdLoaded callback informs your Cordova code when the ad is ready. You can now make the following call:

window.plugins.freestarPlugin.showInterstitialAd(AD_PLACEMENT);

Make sure the placement strings match, if you are using more than one placement. The easiest way to do this is to show the ad from within the onInterstitialAdLoaded callback you added as an event listener for that event:

function onInterstitialLoaded(data) {
    window.plugins.freestarPlugin.showInterstitialAd(data.placement);
}

The ad will now take over the app, and make the appropriate callbacks; the onInterstitialAdDismissed is sent when the ad returns control back to the app.

Rewarded Ads

Rewarded ads behave like interstitial ads, but are augmented with an incentivization mechanism. Typically, the user is rewarded by in-app virtual currency upon completion of the ad. The currency and amount are under your control, and thus need to be passed to window.plugins.freestarPlugin.

To do this, your Cordova code needs to add event listeners to the rewarded ad events:

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

And then request to load an ad:

window.plugins.freestarPlugin.loadRewardedAd(null);

While implementing callbacks is optional, showing an ad before it's loaded will not work. The onRewardedVideoLoaded callback informs your Cordova code when the ad is ready. You can now make the following call:

window.plugins.freestarPlugin.showRewardedAd(
  AD_PLACEMENT, 
  "MySecret1234", //secret key 
  "MyUserId",     //user id
  "Gold Coins",   //reward name
  "100"           //reward amount
  );

Make sure the placement strings match, if you are using more than one placement. The ad will now take over the app, and make the appropriate callbacks; the onRewardedVideoDismissed is sent when the ad returns control back to the app.

The onRewardedVideoCompleted is called before the dismissed callback, and may be called when the ad is still playing. It is an indicator that the reward for the ad may now be given to the app user.

Banner Ads

Banner ads are displayed on top of the app, and only obscure it partially, rather than taking over the screen entirely. Freestar allows you to display either small (320x50) or medium (300x250) banners, and to choose to show them at the top, bottom, or middle of the device screen. You can also receive callbacks for key events in the ad's lifecycle.

To do this, your Cordova code needs to add event listeners to the rewarded ad events:

document.addEventListener('onBannerAdFailed', onBannerAdFailed, false);
document.addEventListener('onBannerAdShown', onBannerAdShown, false);
document.addEventListener('onBannerAdClicked', onBannerAdClicked, false);
document.addEventListener('onBannerAdDismissed', onBannerAdDismissed, false);

And then request the ad. There are no separate load and show calls:

window.plugins.freestarPlugin.showBannerAd(
  null, //the placement string -- null if you don't use multiple placements
  window.plugins.freestarPlugin.BANNER_AD_SIZE_320x50, //banner size
  window.plugins.freestarPlugin.BANNER_AD_SIZE_320x50  //banner position
);

The ad will load and display automatically at the appropriate position. When you no longer need it, you can remove it:

window.plugins.freestarPlugin.closeBannerAd(null, window.plugins.freestarPlugin.BANNER_AD_SIZE_300x250);

Make sure the placement string and size you pass in match.

Working sample

Take a look at the sample project and specifically its www/index.js file.

This working sample shows how to initialize, implement the ad listeners, and show fullscreen Interstitial, Rewarded, and banner ads.