Getting Started with the ironSource Unity Plugin

To begin monetizing your application with the ironSource SDK, follow these 4 easy steps:

  1. Add the IronSource Unity Package to your Project
  2. Additional Settings for Android
  3. Additional Settings for iOS
  4. Set UserID
  5. Initialize the Ad Units
  6. Verify Your Integration

Before You Start

We support Unity version 5 and up.

Step 1. Add the IronSource Unity Package to Your Project

Disclaimer: Updating the ironSource SDK
When upgrading from older SDK versions to the ironSource SDK 6.5+, you must update all mediation adapters. 

Follow these steps to add the IronSource Unity Package to your project:

  1. Download the IronSource Unity Plugin here.
  2. Make sure your Unity project is opened and unzip the Unity Package.
  3. Double-click on the extracted file; the different files will be populated automatically as shown below:
    unity-project

Important! Using the Unity Editor with the ironSource SDK
The ironSource SDK is designed to work with the Android & iOS platform. The Unity Editor contains a Simulator to work with Unity code. In order to work with our plugin, you must target either an Android or iOS build to test the integration.

Step 2. Additional Settings for Android

In the case your application doesn’t have an AndroidManifest, leave the checkbox under Assets ➣ PluginsAndroidIronSource ➣ AndroidManifest.xml checked and skip to Google Play Services integration.
If you do have an AndroidManifest, please uncheck the box and follow the steps below.
  1. Update AndroidManifest.xml
    Add the following to your AndroidManifest.xml:

    • Manifest Permissions
      Add the following permissions to your AndroidManifest.xml file outside the <application> tag: 

      <uses-permission android:name="android.permission.INTERNET" />
      <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    • Manifest Activities
      Add the following activities inside the <application> tag on your manifestAdditions:

      <activity
                  android:name="com.ironsource.sdk.controller.ControllerActivity"
                  android:configChanges="orientation|screenSize"
                  android:hardwareAccelerated="true" />
      <activity
                  android:name="com.ironsource.sdk.controller.InterstitialActivity"
                  android:configChanges="orientation|screenSize"
                  android:hardwareAccelerated="true"
                  android:theme="@android:style/Theme.Translucent" />
      <activity
                  android:name="com.ironsource.sdk.controller.OpenUrlActivity"
                  android:configChanges="orientation|screenSize"
                  android:hardwareAccelerated="true"
                  android:theme="@android:style/Theme.Translucent" />
  2. Google Play Services
    We recommend using Google Play Services as the ironSource Plugin requires the Android Advertising ID to ensure ad inventory at scale. Follow this guide on how to integrate the Google Play Services AAR.

Step 3. Additional Settings for iOS

  1. Add Ad-Support.framework to Your Xcode Project
    Our Unity Plugin usually adds all the required frameworks automatically. In some cases, the AdSupport.framework can’t be added automatically using Unity 5. Verify if the framework has been added and in the case it has not been added automatically, make sure to add it manually.
  2. iOS9 App Transport Security Settings
    Important!
     In iOS9, Apple has added in controls around ‘ATS’. In order to ensure uninterrupted support for ironSource Ad delivery across all Mediation Networks, it’s important to make the following changes in your info.plist:

    • Add in a dictionary called ‘NSAppTransportSecurity‘. Make sure you add this dictionary on the ‘Top Level Key‘.
    • Inside this dictionary, add a Boolean called ‘NSAllowsArbitraryLoads‘ and set it to YES.
      Supersonic iOS9 App Transport Security Settings
      Note: Make sure that your info.plist does not contain any other exceptions besides ‘NSAllowsArbitraryLoads‘, as this might create a conflict.

Step 4. Set userID

If you’re serving the Offerwall ad unit or using server-to-server callbacks to reward your users with our rewarded ad units, you must set the UserID.

The userID is a unique identifier for each of your users. You can set the userID parameter, or omit it and let us generate one for you. If you choose to skip setting the userID in your code, the SDK will generate an equitable userID.

We support NSString from 1 to 64 characters. Common practice is to use the Google Advertising ID (GAID) or Apple Advertising ID (IDFA). More information on User IDs can be found here.

Note: In the case you want to define the userID manually, you must do this before the init request. You cannot define the userID after the init request. 
IronSource.Agent.setUserId(YOUR_USER_ID);

Step 5. Initialize the Ad Units

First, you’ll need to pass the state of the application by executing the following event function during the Application Lifecycle.

Call onApplicationPause in each of the Unity Scenes:

void OnApplicationPause(bool isPaused) {                 
  IronSource.Agent.onApplicationPause(isPaused);
}

Next, initialize the ironSource ad units.

New! You can now initialize the SDK in two ways. We recommend the first method as it will fetch the specific ad units you define.
This method will init the specific ad units mentioned in the adUnits parameter:

IronSource.Agent.init (YOUR_APP_KEY, IronSourceAdUnits.REWARDED_VIDEO, IronSourceAdUnits.INTERSTITIAL, IronSourceAdUnits.OFFERWALL, IronSourceAdUnits.BANNER);

Alternatively, you can init the SDK as detailed below and the SDK will init the ad units you’ve configured on the ironSource platform:

IronSource.Agent.init (YOUR_APP_KEY);

Optional: ironSource supports Network Change Status, which enables the SDK to change the availability according to network modifications, i.e. in the case of no network connection, the availability will turn to FALSE. The default of this function is False; in the case you’d like to utilize it, you can activate it in the Init with the following string:

IronSource.Agent.shouldTrackNetworkState (true);

Step 6. Verify Your Integration

The ironSource SDK provides an easy way to verify that your Rewarded Video Mediation integration was completed successfully. To verify your ironSource SDK integration as well as any additional Ad Networks you have implemented, simply add this method to your project:

IronSource.Agent.validateIntegration();

For more details on the ironSource Integration Verification tool navigate to this article.

For Proguard Users Only

If you are using ProGuard with the ironSource SDK, you must add the following code to your ProGuard file (Android Studio: proguard-rules.pro or Eclipse: proguard-project.txt):

-keepclassmembers class com.ironsource.sdk.controller.IronSourceWebView$JSInterface {
    public *;
}
-keepclassmembers class * implements android.os.Parcelable {
    public static final android.os.Parcelable$Creator *;
}
-keep public class com.google.android.gms.ads.** {
   public *;
}
-keep class com.ironsource.adapters.** { *;
}

Done!
You are now ready to start working with ironSource’s Ad Units and Mediation Tools.


What’s Next?

Once you’ve verified your integration with the Integration Helper, follow our integration guides and implement our Ad Units:

Interested in Mediation? Integrate our Rewarded Video or Interstitial Ads in your app and follow our Mediation articles.