Unity integration

SDK Version: 3.1.4

This document describes the basic procedure for integrating Start.io In-App Ads for Unity into your Android/iOS applications for publishers using Start.io SDK directly.

After this simple integration process, Start.io In-App Ads enables you to reap the benefits of Start.io's In-App monetization products, which maximize the revenue generated by your application. All this profit-making is achieved with minimal effort and minimal interference with your users' experience.

Getting Started

Step 1, Adding the SDK package to your Unity project

In order to add Start.io SDK to your application please follow the following steps:

1. Unzip the SDK files to a temporary folder
2. Import StartIOUnitySDK-x.x.x.unitypackage as a Custom Package (or drag and drop it to your "Assets" folder under the "Project" Window)

3. Import all the package's items by pressing "All" and then "Import".
If you are using a custom AndroidManifest.xml and don't want to override it with the one provided by this package, just uncheck the "AndroidManifest.xml". In this case, you must update the manifest manually as described in the next step. 

Step 2, Updating your Manifest File

Update the manifest.xml (in the Android folders) as follow:

1. Add the following mandatory permissions

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

2. Optional - add the following permissions (allow Start.io to show higher eCPM Geo-targeted ads):

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
<uses-permission android:name="android.permission.BLUETOOTH" />

3. Make sure the following android components under the <application element>:

<provider
    android:name="com.startapp.sdk.adsbase.StartAppInitProvider"
    android:authorities="${applicationId}.startappinitprovider"
    tools:node="remove" />

<activity
    android:name="com.startapp.sdk.adsbase.consent.ConsentActivity"
    android:configChanges="orientation|screenSize|screenLayout|keyboardHidden"
    android:theme="@android:style/Theme.Translucent"/>

<activity
    android:name="com.startapp.sdk.ads.list3d.List3DActivity"
    android:theme="@android:style/Theme"/>

<activity
    android:name="com.startapp.sdk.adsbase.activities.OverlayActivity"
    android:configChanges="orientation|screenSize|screenLayout|keyboardHidden"
    android:theme="@android:style/Theme.Translucent"/>

<activity
    android:name="com.startapp.sdk.adsbase.activities.FullScreenActivity"
    android:configChanges="orientation|screenSize|screenLayout|keyboardHidden"
    android:theme="@android:style/Theme"/>

<service android:name="com.startapp.sdk.adsbase.InfoEventService" />
<service
    android:name="com.startapp.sdk.adsbase.PeriodicJobService"
    android:permission="android.permission.BIND_JOB_SERVICE" />

<receiver android:name="com.startapp.sdk.adsbase.remoteconfig.BootCompleteListener">
    <intent-filter>
        <action android:name="android.intent.action.BOOT_COMPLETED"/>
    </intent-filter>
</receiver>

 4. Make sure the meta-data parameter named unityplayer.ForwardNativeEventsToDalvik is set to true:

<meta-data android:name="unityplayer.ForwardNativeEventsToDalvik" android:value="true" />

Step 3, Initialization

Update the StartAppDataAndroid.txt file for Android and StartAppDataiOS.txt for iOS (in the Assets/Resources folders) by adding your Start.io Application ID (replace the ApplicationId) after applicationId=

You can find your Application ID in the developers’ portal - click on the "Apps and Sites" tab on the left pane and choose the relevant ID from your app list:

User Consent

Consent from European Users (GDPR)

Start.io requires you to pass user consent flag via the API as detailed herein below. The user consent flag indicates whether a user based in the EU has provided consent for ads personalization, collection and use of personal data. Based on this consent flag, Start.io will be able to use the data to target the most relevant ads to your users. If a user has not consented, we will not show personalized ads to this user.

Use this method in case the user has consented:

AdSdk.Instance.SetUserConsent(
 "pas",
 true,
 (long)DateTime.UtcNow.Subtract(new DateTime(1970, 1, 1)).TotalMilliseconds);

Use this method in case the user has not consented:

AdSdk.Instance.SetUserConsent(
 "pas",
 false,
 (long)DateTime.UtcNow.Subtract(new DateTime(1970, 1, 1)).TotalMilliseconds);

NOTE: timestamp parameter should represent the specific time a consent was given by the user.

To make the process easier, we have added a consent window to our demo apps. Please follow the link to see demo projects. 

Unity sample consent window:

Ad Formats

Splash Ad (Depracted)

A Splash Ad is a full-page ad that is displayed immediately after the application is launched. A Splash Ad first displays a full page splash screen that you define (as described below) followed by a full page ad.

First, import the sdk namespace

 using StartApp;

Then, in the Start() method of your script, call the following static function: 

void Start() {
    AdSdk.Instance.ShowSplash();
}

If you wish to customize the splash screen use SplashConfig object:

 void Start() {
    var config = new SplashConfig {
        TemplateTheme = SplashConfig.Theme.Blaze
    };
    AdSdk.Instance.ShowSplash(config);
 }

You are able to setup

1. TemplateTheme - just color theme (see enum values)
2. Orientation - the supported orientations by your app
3. AppName - any string which will be displayed as your app title
4. LogoFileName - your logo which will be displayed in the center of the screen, if you skip it your app icon will be used instead

Return Ad (Depracted)

The Return Ad is a new ad unit which is displayed once the user returns to your application after a certain period of time. To minimize the intrusiveness, short time periods are ignored. For example, the Return Ad won't be displayed if the user leaves your application to take a short phone call before returning.

Return ads are enabled and activated by default. If you want to disable this feature, simply change "returnAds" value to "false" in your StartAppDataAndroid.txt or StartAppDataiOS.txt file (see "Step 3" above):

returnAds=false;

Or just call:

void Start()
{
    AdSdk.Instance.DisableReturnAds();
}

Exit Ad

Exit Ad is available on Android only, on iOS you can leave the code but it does nothing.

void Update() {
    if (Input.GetKeyUp(KeyCode.Escape)) {
        AdSdk.Instance.OnBackPressed();
    }
}

Use this call in components where you would like the user to press 'back' to exit the application. The plugin will show an ad and then exit the application.

Interstitial Ads

You can choose to show the interstitial ad in several locations within your application. This could be upon entering (Start()), between stages, while waiting for an action and more.

We do, however, recommend showing the ad upon exiting the application by using the ‘Back’ button, as explained in the previous section.

Add the following code to the appropriate place or places within your activities in which you would like to show the ad:

Import the sdk namespace

 using StartApp;

Show the ad

void Start() {
    AdSdk.Instance.ShowDefaultAd();
}

Customized Interstitial Ads

In customized ads you are able to create separated ad instances, set event listeners and choose desired ad type for them.

You need to create the instance of the ad, add load event listener, load desired ad type and call show ad from the listener or when you needed (probably when an user clicks the button):

void Start() {
    var ad = AdSdk.Instance.CreateInterstitial();
    ad.RaiseAdLoaded += (sender, e) => { ad.ShowAd(); };
    ad.LoadAd(InterstitialAd.AdType.Automatic);
}

If you have problem with ad showing use RaiseAdLoadingFailed event and print the error message:

ad.RaiseAdLoadingFailed += (sender, e) => { Debug.Log(string.Format("Error {0}", e.Message)); };

You are able to handle 'ad clicked', 'ad closed' and 'rewarded video completed' events as well:

ad.RaiseAdShown += (sender, e) => Debug.Log("AdShown");
ad.RaiseAdClosed += (sender, e) => Debug.Log("AdClosed");
ad.RaiseAdClicked += (sender, e) => Debug.Log("AdClicked");
ad.RaiseAdVideoCompleted += (sender, e) => Debug.Log("RewardedVideoCompleted");

You can call LoadAd with following parameters:

1. Automatic - available in the user's country and most valuable ad
2. FullScreen - simple interstitial ad
3. OfferWall - several ads on one page, available only on Android, on iOS loads Automatic
4. Video - simple video ad
5. Rewarded - rewarded video ad

Rewarded Video Ads

Rewarded Ads are interstitial video ads that provide a reward to the user in exchange for watching an entire video ad. The reward might be in-app goods, virtual currency or any premium content provided by the application. Because users actually opt-in to watch a rewarded video and are granted with something valuable in return, Rewarded Ads are an effective and clean monetization solution for stronger user retention and keeping users engaged in your application for a longer amount of time.

In order to show a Rewarded Ad, follow the next steps:

Inside your Start() method, declare a video listener and load the rewarded video ad:

void Start() {
    var ad = AdSdk.Instance.CreateInterstitial("adTagIfNeeded");
    ad.RaiseAdLoaded += (sender, e) => ad.ShowAd();
    ad.RaiseAdVideoCompleted += (sender, e) => { Debug.Log("Give the reward here"); };
    ad.LoadAd(InterstitialAd.AdType.Rewarded);
}

if (ad.IsReady()) {
    ad.ShowAd();
}

Banner Ads

To add a banner to your application add the following code in the appropriate place:

Import the SDK namespace

 using StartApp;

Display the banner

void Start() {
    AdSdk.Instance.ShowDefaultBanner();
}

Parameters

BannerAd.BannerPosition - position of the banner. Can receive one of the following: 
BannerAd.BannerPosition.Top
BannerAd.BannerPosition.Bottom

by default it's bottom

You can set tag as well:

void Start() {
    var banner = AdSdk.Instance.CreateBanner();
    banner.ShowInPosition(BannerAd.BannerPosition.Top);
}

Customized Banner Ads

You are able to create separated banner instances and set event listeners on them.

Create the instance and show it in desired position:

void Start()
{
    var banner = AdSdk.Instance.CreateBanner();
    banner.ShowInPosition(BannerAd.BannerPosition.Top);
}

If you have problem with banner showing use RaiseBannerLoadingFailed event and print the error message:

banner.RaiseBannerLoadingFailed += (sender, e) => { Debug.Log(string.Format("Error {0}", e.Message)); };

You are able to handle 'banner shown' and 'banner clicked' events as well:

banner.RaiseBannerShown += (sender, e) => Debug.Log("BannerShown");
banner.RaiseBannerClicked += (sender, e) => Debug.Log("BannerClicked");

If you need to check whether the banner is presented in particular position use the following method:

if (!banner.IsShownInPosition(BannerAd.BannerPosition.Top)) {
    banner.ShowInPosition(BannerAd.BannerPosition.Top);
}

If you need to hide the banner just call Hide method:

banner.Hide();

And if you want to preload a banner in advance call PreLoad before showing:

banner.PreLoad();

In case you 0like to display MRec ads please use the below:

banner.ShowInPosition(BannerAd.BannerPosition.Top, "myBannerTag", BannerAd.BannerType.Mrec);

In case you would like to display Cover ads please use the below:

banner.ShowInPosition(BannerAd.BannerPosition.Top, "myBannerTag", BannerAd.BannerType.Cover);

Open-source code

The Unity Plugin's source code is available on GitHub. You can use, modify, refactor or fix it according to Apache 2.0 license.

For running the sample just open the project in Unity editor, press File -> Build Settings then Switch to iOS or Android platform and press "Build And Run" button.

For exporting the .unitypackage:

1. Select Assets folder, right click on it and choose Export Package
2. Select all except Scenes and press Export
3. Name it as StartAppUnitySDK-[version].unitypackage and save in an appropriate location.

We require that all contributions to our projects are accompanied by a signed contributor license agreement (CLA) before we can accept them. Please send a signed copy of the Open Source Contribution license to oss-contribution@start.io

Start.io 2022