Freestar Ads Mediation - Unity Integration Guide for iOS

• Unity 2020 or newer

• Xcode 13 and iOS 11 or higher

• Cocoapods

Please follow the instructions in order.

Make sure you switched to iOS:

Other settings: Target minimum iOS version: 11.0

Other settings: Graphics API: Open GLES2

Other settings: Target SDK: Either Simulator SDK or Device SDK Unity iOS projects are generated for one or the other, but not both.

Download FreestarMediation.unitypackage

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

Assets: Import Package: Custom Package

Hit the Import button.

1. Add this line in the pod file and save it. Before saving you can exclude (by removing the pod dependencies) any mediation partners that you don’t want to integrate (Please contact your account manager for more details):

   Podfile:
   use_frameworks! :linkage => :static
   

2. Run `pod install —-repo-update` to download and install the latest version.
3. Open the `.xcworkspace` file by double clicking it.
4. Go to:
   Pods → Target Support Files → Pods-UnityFramework → Pod-UnityFramework-resources.sh And delete below lines:

   install_resource "${BUILT_PRODUCTS_DIR}/FreestarAds/FreestarAds.framework/Freestar-Native-Medium.nib"
   install_resource "${BUILT_PRODUCTS_DIR}/FreestarAds/FreestarAds.framework/Freestar-Native-Small.nib"
   

   
   There could be more than one instance of these lines depending on the number of "$CONFIGURATION". Please make sure to delete these two lines from all configurations.
5. Add `/usr/lib/swift` to your Run Search Paths Xcode build setting.
6. Add and embed below shown frameworks.

   

7. Go to -> Libraries -> com.unity.ads -> plugin -> iOS

   Select all files under this and deselect the ‘UnityFramework’ under target membership on right hand side.

   

One of the files imported in the FreestarMediation package is the dependencies spec: Editor/FreestarMediationDependencies.xml. This will be used to generate the Podfile for the Xcode project. The relevant section is the following:

 <iosPods>
    <iosPod name="FreestarAds" version="~> 5.11.0"></iosPod>
    <iosPod name="FreestarAds-AdColony" version="~> 5.2.0"></iosPod>
    <iosPod name="FreestarAds-AppLovin" version="~> 11.0.0"></iosPod>
    <iosPod name="FreestarAds-AppLovinMax" version="~> 11.0.0"></iosPod>
    <iosPod name="FreestarAds-Tapjoy" version="~> 12.8.0"></iosPod>
    <iosPod name="FreestarAds-Googleadmob" version="~> 9.2"></iosPod>
    <iosPod name="FreestarAds-Googleadmob/Facebook" version="~> 9.2"></iosPod>
    <iosPod name="FreestarAds-GAM" version="~> 9.2"></iosPod>
    <iosPod name="FreestarAds-GAM/Facebook" version="~> 9.2"></iosPod>
    <iosPod name="FreestarAds-TAM" version="~> 4.4.3.2"></iosPod>
    <iosPod name="FreestarAds-Criteo" version="~> 4.3.1.1"></iosPod>
    <iosPod name="FreestarAds-Unity" version="~> 6.1.0"></iosPod>
    <iosPod name="FreestarAds-Vungle" version="~> 6.10.6"></iosPod>
    <iosPod name="FreestarAds-Pangle" version="~> 3.7.0.8"></iosPod>
    <iosPod name="FreestarAds-Yahoo" version="~> 1.14.2"></iosPod>
    <iosPod name="FreestarAds-Hyprmx" version="~> 6.0.0"></iosPod>
  </iosPods>
</dependencies>

You may wish to only include some ad partners. Remove or comment out the lines listing those you do not wish to use. However, the FreestarAds pod is required.

Within your Unity app, you need to initialize the Freestar SDK. After you imported the FreestarMediation package, you can use the C# code within by importing the Freestar namespace:

import Freestar;

Now you will be able to call methods in Freestar classes, the most important of which is the FreestarUnityBridge. You will need a Freestar API Key, and pass it to the initializer. For efficiency, it is best to do this as soon as possible within your app's lifecycle.

FreestarUnityBridge.initWithAPIKey(YOUR_API_KEY);

This will initialize the SDK and enable it to run ads. The Freestar Unity plugin supports two types of fullscreen ads: interstitial and rewarded, and banner ads in two sizes: 320x50 display points, and 300x250 display points.

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 Unity code needs to implement the FreestarInterstitialAdCallbackReceiver interface:

void onInterstitialAdLoaded(string placement);
void onInterstitialAdFailed(string placement);
void onInterstitialAdShown(string placement);
void onInterstitialAdClicked(string placement);
void onInterstitialAdDismissed(string placement);

And then pass in the object that implements this interface to FreestarUnityBridge:

FreestarUnityBridge.setInterstitialAdListener(this);

Finally, you request to load an ad:

FreestarUnityBridge.loadInterstitialAd (AD_PLACEMENT);

Note: there are additional detailes 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 an empty string:

FreestarUnityBridge.loadInterstitialAd ("");

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

FreestarUnityBridge.showInterstitialAd (AD_PLACEMENT);

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 onInterstitialAdDismissed is sent when the ad returns control back to the app.

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 FreestarUnityBridge.

To do this, your Unity code needs to implement the FreestarRewardedAdCallbackReceiver interface:

void onRewardedAdLoaded(string placement);
void onRewardedAdFailed(string placement);
void onRewardedAdShown(string placement);
void onRewardedAdFinished(string placement);
void onRewardedAdDismissed(string placement);

And then pass in the object that implements this interface to FreestarUnityBridge:

FreestarUnityBridge.setRewardedAdListener(this);

Finally, you request to load an ad:

FreestarUnityBridge.loadRewardedAd (AD_PLACEMENT);

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

FreestarUnityBridge.showRewardedAd (
  AD_PLACEMENT, //use "" if you don't need multiple placements
  50,           //reward amount
  "Coins",      //reward name
  "Freestar1"   //User ID, use "" if not utilized
  "SECRET_KEY"  //An optional secret for greater security, use "" if not utilized
);

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 onRewardedAdDismissed is sent when the ad returns control back to the app.

The onRewardedAdFinished 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 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 Unity code needs to implement the FreestarBannerAdCallbackReceiver interface:

void onBannerAdShowing(string placement, int adSize);
void onBannerAdClicked(string placement, int adSize);
void onBannerAdFailed(string placement, int adSize);

And then pass in the object that implements this interface to FreestarUnityBridge:

FreestarUnityBridge.setBannerAdListener(this);

Finally, you request the ad. There are no separate load and show calls:

FreestarUnityBridge.ShowBannerAd(
  "", //the placement string -- empty if you don't use multiple placements
  FreestarConstants.BANNER_AD_SIZE_320x50,  //banner size
  FreestarConstants.BANNER_AD_POSITION_TOP  //position
);

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

FreestarUnityBridge.CloseBannerAd("",FreestarConstants.BANNER_AD_SIZE_320x50);

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

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.

Please use test key 91784edd-3492-4111-8742-f71bd3803dd3

After creating the app flow in Unity, you can have it generate an Xcode project: File->Build Settings will open the settings window, with a Build button. This will only work on a Mac that has Xcode and Cocoapods installed; you will be prompted for a save location, and Unity will create an Xcode project. Within the generated folder, make sure to open the .xcworkspace file. You will now have a generated Xcode project capable of building a working iOS app with Freestar Ads integrated.

However, there are several things to keep in mind. If, in the FreestarMediationDependencies.xml file (see above), you've asked to include either FreestarAds-Googleadmob or FreestarAds-GAM pods, you will need to modify the generated app's Info.plist file to include the following:

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

The key is obtained from Google, without it, an app that integrates either of its Ad SDKs cannot run.

There are also potential build errors due to Unity-iOS compatibility issues, that depend on the version of Unity and Xcode involved. Two known ones are resolved as follows:

Some version of Unity generate invalid Metal-related code; this produces a compilation error when attempting to build the app in the MetalHelper.mm file. The issue can be resolved by commenting out the following section:

#if PLATFORM_IOS || PLATFORM_TVOS
    if (@available(iOS 10.3, tvOS 10.2, *))
    {
        const int targetFPS = UnityGetTargetFPS(); assert(targetFPS > 0);
        [UnityCurrentMTLCommandBuffer() presentDrawable: surface->drawable afterMinimumDuration: 1.0 / targetFPS];
        return;
    }
#endif

There is a fallback outside the macro, so the removal of the code does not break the rest of the architecture.

iOS apps generated with Unity 2018 will not build for the simulator in recent versions of Xcode. Builds for device work correctly.

Unity Xcode projects are generated with modules disabled, this means convenience headers in the style:

@import UIKit;

don't work. Some versions of the FreestarAds SDK include such a declaration in the FreestarPrerollAd.h header. Xcode will flag the compiler error, the solution is to open the header and replace the statement:

@import AVKit;

With the equivalent:

#import <AVKit/AVKit.h>

Now, the Xcode will build the app and you can run it on your device or simulator as if it was a native app.