Unity integration

SDK Version: 1.0.7

This document describes the basic procedure for integrating StartApp In-App Ads for Unity into your Android/iOS applications.

After this simple integration process, StartApp In-App Ads enables you to reap the benefits of StartApp'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.

NOTES:
  • The code samples in this document can be copy/pasted into your source code
  • Please notice that steps 1-4 are mandatory
  • If you have any questions, contact us via support@startapp.com

 

Getting Started

Step 1, Adding the SDK package to your Unity project

In order to add StartApp SDK to your application please follow the following steps:

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

Screen_Shot_2019-01-21_at_2.09.13_PM.png

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. 

Screen_Shot_2019-01-21_at_2.09.44_PM.png

Step 2, Updating your Manifest File

NOTES:

If you are using a custom AndroidManifest.xml and didn't import it in the previous step, make sure to follow this step. If you have imported the entire package you can skip this step and move on to step 3.

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

1. Make sure the following activities are declared under the <application> element:


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

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

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

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

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

3. Add the following service receiver under the element:

<service android:name="com.startapp.android.publish.common.metaData.PeriodicMetaDataService" />
<service android:name="com.startapp.android.publish.common.metaData.InfoEventService" />
<receiver android:name="com.startapp.android.publish.common.metaData.BootCompleteListener" >
	<intent-filter>
		<action android:name="android.intent.action.BOOT_COMPLETED" />
	</intent-filter>
</receiver>

4. 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"/>

5. Optional - add the following permissions (allow StartApp 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" />

 

Step 3, Initialization

Updating your StartApp data file

Update the StartAppDataAndroid.txt file for Android and StartAppDataiOS.txt for iOS (in the Assets/Resources folders) by adding your StartApp 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:

 

Step 4, User Consent (GDPR)

StartApp 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, StartApp 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.

IMPORTANT NOTES:
  • Collection of consent is only required in countries covered by GDPR (EU member states). Consent is not required for users that are based outside those countries.
  • We recommend you to pass the consent flag to StartApp right after initializing the SDK.
  • In case of any consent change during the lifetime of the user activity, you are required to re-submit the relevant consent flag to StartApp.
  • Older SDK versions (before 3.9.1): We'll continue to support them with showing ads. It’s important to know that in case you cannot update the SDK version and the user consent is false for GDPR users, do not initialize StartApp SDK for such users.

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:

Consent_window_demo.png

Splash Ad (recommended)

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.

  • StartApp Splash Ad is a top performing ad unit, presenting the industry's highest CPM's
  • supported for Unity v4.2 and above

 

Adding the Splash Screen

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

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.

NOTE:

there is no need to implement exit on the 'back' button in these components as the plugin will exit the application after showing the ad.

 

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("adTagIfNeeded");
};
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();
ad.RaiseAdLoaded += (sender, e) => ad.ShowAd();
ad.RaiseAdVideoCompleted += (sender, e) => {
// Give the reward here
Debug.Log("VideoCompleted");
}
ad.LoadAd(InterstitialAd.AdType.Rewarded);
}
IMPORTANT:

Loading an ad might take a few seconds especially in the case of a video, so it's important not to show the ad immediately after you initiated loading process. In case you call showAd() while the ad hasn't been successfully loaded yet, nothing will be displayed. It is recommended to use the "RaiseAdLoaded" callback which is triggered when an ad was loaded and ready to use. Or you are able to use IsReady method which tells you whether the ad has been loaded successfully.

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()
{
AdSdk.Instance.ShowDefaultBanner(BannerAd.BannerPosition.Top, "bannerTag");
}

 

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();

 

Open-source code

The unity wrapper'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... Switch to iOS or Android platform and press "Build And Run" button.

For exporting the .unitypackage select Assets folder, right click on it and choose Export Package... Select all except Scenes and press Export... 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@startapp.com

 

StartApp 2019

 

Was this article helpful?
0 out of -3 found this helpful

Articles in this section