Unity SDK Integration

893ad6d-Unity_icon.png

Current SDK Version: 3.9.0

 

Introduction

This guide is intended for developers who are integrating the FairBid SDK with a Unity app. After you have integrated the SDK, you must choose the relevant ad format and follow the steps for implementing that format.

Prerequisites

  • Android 4.1 (API level 16)+ (when building for Android)
  • iOS 9.0+ (when building for iOS)
  • Unity 2017 LTS or later

Important

  • The FairBid Unity SDK can only build iOS projects from a Mac - you cannot build your Xcode project on Windows.
  • All Fyber SDKs and supported mediated networks work in conjunction with Android's 64-bit architecture.

Manual Download

 
 
 

Removing Current Plugin

If you are updating the Plugin, first make sure there is no trace of the previous version of the FairBid Plugin.

Simply remove the FairBid folder. This is a fail-safe way to ensure no legacy file is left behind:

67626ea-Unity1.png

If your current FairBid Plugin pre-dates version 3.4.1 refer to Migrating from the Old to New Structure below to ensure it is correctly removed.

Importing New Plugin

  1. Download the FairBid SDK
  2. Unzip the downloaded files
  3. Add the FairBid.unitypackage to your open Unity project.

You can do this by either double-clicking the file, or following the steps outlined in the below screenshot:

20753aa-unity_install__1_.png

Migrating from Old to New Structure

Before FairBid Unity Plugin 3.4.1, the plugin resources would be spread out across unity folders:

fc8e3c3-Unity_2.png

Starting from version 3.4.0 we have moved all relevant resources inside a FairBid folder.

This makes it more convenient when updating the plugin and helps maintain the organization of the project folders.

If you are moving from a previous version, make sure to delete all traces of the FairBid plugin before importing the new package.

These are all the files you must delete:

21ffe13-Unity_3.png

This prevents build issues due to file duplications.

Moving forward, the update process should be seamless. For more information refer to the Integration sections below.

Android Specific Setup

Enable Gradle Template

For Android builds, it is highly recommended to enable the Gradle template.

This allows you to configure your build to include specific dependencies, build properties and other compilation options in a seamless way.

To do this, select the “Custom Gradle Template” box in Publishing Settings.

8d61c8b-Unity_6.png

This creates a file called mainTemplate.gradle under Assets/Plugins/Android.

Kotlin Standard lib

Starting from SDK 3.5.0, the FairBid SDK makes use of the kotlin standard lib.

You must declare the following dependency in yourmainTemplate.gradle file:

dependencies {
    implementation 'org.jetbrains.kotlin:kotlin-stdlib:1.3.72'
}

Installing Google Play Services

The Google Play Services Ads Identifier must be added to your project.

You must declare the following dependency in your mainTemplate.gradle file:

dependencies {
    implementation 'com.google.android.gms:play-services-ads-identifier:17.0.0' 
}

Java Version Compatibility

Starting from FairBid SDK 3.0.0, if you support android SDK below 26 and you are using Unity Editor lower than 2018 LTS (2018.4.20f1), you must declare the source and target compatibility of your project to Java 1.8.

You must declare the following dependency in your mainTemplate.gradle file:

android {
    ...
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
    ...
}

Historically, Android projects have been using Java 1.7 since it was the surest way to ensure compatibility across Android versions.

Android Studio has been supporting partial compatibility with Java 1.8 since version 3.0.0. As some of our partners begin moving to 1.8, we follow suit.

It simply allows our team (and our partners) to leverage some new features of the Java language with no implications on runtime/API compatibility.

However, it enforces the same type of declaration in the projects integrating FairBid SDK.

Building for Android X

If you, or any of your integrated mediation networks use AndroidX libraries, you can update your build to ensure compatibility.

To use androidx-namespaced libraries in a new project, you must set the compile SDK to Android 9.0 (API level 28) or higher.

You can add the gradle properties that ensure build compatibility with android adding the following entries to you mainTemplate.gradle file (at the root level):

project.ext.set('android.useAndroidX', true)
project.ext.set('android.enableJetifier', true)

For more information about AndroidX, click here.

Using Proguard

If you decide to use proguard in your setup, there might be some incompatibilities. The Unity editor might set the flag useProguard in your mainTemplate.gradle file. This flag is deprecated and, depending on your Android Gradle plugin version, your build might fail.

If you want to prevent this error, set the following entry in your mainTemplate.gradle file:

project.ext.set('android.enableR8', true)

iOS Specific Setup

Disabling Multi-Tasking Setup

iOS 9 added multitasking support. However, this interferes with an ad's ability to set the orientation of the app.

For ads to show properly, you must disable this feature.

You can do this from the Player Settings by checking the box labeled Requires Fullscreen.

b61a3b0-Unity_7.png

 

Preventing build issues on Unity 2019.3 and above

The Xcode project structure has changed as of Unity 2019.3 to support Unity integration into native iOS applications via Unity as a Library. More info here.

This leads to build issues related to a missing Library link the FairBid SDK relies on: CoreLocation

That's a result on both the architectural change in the Xcode project and the fact Unity does not include CoreLocation as a default dependency when generating the Xcode project

There are 2 alternative ways for fixing this problem:

Editing Xcode project Build Settings

By "enabling modules (C and Objective-C)", Xcode will link all declared dependencies at build time. This includes the CoreLocation which FairBid relies on but Unity does not include by default.

This is how you do that:

  1. In the Xcode project, go to the project settings and select the Build Settings tab.
  2. Under TARGETS, select "UnityFramework".
  3. In Build Settings, search for the term "modules". Under the section "Apple Clang - Language - Modules", set the "Enable Modules (C and Objective-C)" to "Yes"

Adding the missing library the FairBid framework through Unity UI

Alternatively, you can simply leverage Unity's UI to declare the library FairBid framework relies on: CoreLocation.
This is how you do that:

  1. Before generating Xcode project, in Project panel navigate to Assets > FairBid > Plugin > iOS and select FairBidSDK.framework 
  2. Select the “CoreLocation” box in FairBidSDK.framework Platform Settings.

 

image.png 

Adding 3rd Party SDKs

For details instruction on how to integrated our mediated partners, check Supported Networks and their SDKs page here.