Get Started

Release version: 3.0.2 | Release date: 17.01.2023

Beta release version: 3.1.3-beta.1 | Release date: 29.05.2023 

Follow this guide to get the best out of Appodeal.

The Appodeal SDK gives you access to 70+ Ad Demand Sources and makes them compete against each other in a real-time auction, maximizing your ad revenues. The Appodeal SDK also provides In-app Bidding, Automatic UA Optimization, User Segmentation & A/B Testing, Cross-Promotion and Direct Deals, Instant Payouts, and much more.

Appodeal SDK provides two ways of integration. From the options below, choose the one that fits your needs better:

  1. The Appodeal SDK Full Package - The Appodeal SDK provides you with tools to grow your mobile apps and games. In addition to the monetization services, you can benefit from UA (User Acquisition) and in-app analytics services. 
    Here is the list of services Appodeal SDK Full Package includes :
    • Get started with Appodeal to gain access to Monetization and Analytics.

    • Connect with Adjust or Appsflyer to unlock Attribution features.

    • Connect with Meta (formerly known as facebook-core) for User Acquisition.

    • Connect with Firebase for Analytics + remote config for product A/B tests and settings.

    If you plan to run UA campaigns, want to analyze your metrics in our Appodeal’s business intelligence tool without using MMP, or want to use remote config for tests and settings, your option is - the full package.

  2. The Appodeal SDK Mediation only - If you do not plan to run (UA) User Acquisition campaigns, nor want to use Appodeal advanced analytics, we have created a lite version of our SDK, only with mediation. 
    During the integration, you will not be required to install any additional services apart from mediation. This may speed up your integration process, and you can always upgrade to the Full Package whenever you’re ready.

Please follow this integration guide step by step and choose your integration option when needed.

Also, remember that you can always customize Appodeal SDK with the help of our Appodeal Plugin Manager guide.

The following document shows how to integrate Appodeal in your Unity project with your desired networks, and configure all your ad formats.

Minimum requirements:

  • Unity 2019.4+, 2020.3.16+, 2021.1.17+ 

  • Android API level 21 (Android OS 5.0) and above

  • iOS 12.0 or higher

  • Use XCode 14 or higher

  • CocoaPods 1.10.0 or higher
  • Git must be installed on your device

You can use our  demo app  as a reference project.


Check our video guide on how to integrate Appodeal SDK in your app.


 

Import SDK

Our API has slightly changed compared to the manual distribution method, so you might need to update your scripts accordingly. Check the Upgrade Guide for more details.
Make sure to remove the previously installed Appodeal Plugin via the corresponding tool at the top menu: 'Appodeal → Remove plugin'.

Copy the link below, head to the Window → Package Manager → "+" → Add package from git URL, paste the copied link there and press enter. (Import EDM if prompted)

https://github.com/appodeal/appodeal-unity-plugin-upm.git#v3.0.2

Use Appodeal SDK Manager to update to the latest Appodeal SDK from the Unity menu bar (Appodeal → Manage Appodeal SDK), supports Unity 2018.3 or higher. More information you can find in our blog.

Configure Project

In case you would rather use the Appodeal SDK Full Package along with its services, please ensure you have not excluded them in your project (go to Appodeal → Plugin Configuration).

Please read our Appodeal Plugin Manager guide for more detailed information.

Android Configuration

Gradle settings 

Preparing your Gradle build for Android 11

Android 11 changes how apps can query and interact with other apps that the user has installed on a device. For that reason make sure you're using Gradle version that matches one of listed here .

If you have Unity version 2022 +, please check this guide

  1. Go to Player Settings Publishing Settings and enable Custom Base Gradle Template flag.
  2. Go to AssetsPlugins Android baseProjectTemplate.gradle, open the file and change classpath 'com.android.tools.build:gradle:3.6.0' to 'com.android.tools.build:gradle:3.6.4 '.

If you have already been using Gradle plugin 4.0.1 version or higher, no change is required.

External Dependency Manager

Appodeal Unity Plugin includes External Dependency Manager package. You need to complete these following steps to resolve Appodeal's dependencies:

1. Before switching to Android platform, select  File → Build Settings → Android  in Unity menu bar.

2. Add flag Custom Gradle Template for Unity 2017.4 - Unity 2019.2 versions or for Unity 2019.3 and higher activate the following toggles under Build Settings → Player Settings → Publishing settings:

    • Custom Main Gradle Template
    • Custom Gradle Properties Template

3. Enable the setting "Patch mainTemplate.gradle" (Assets → External Dependency Manager → Android Resolver → Settings).

4. Enable the setting "Use Jetifier" (Assets → External Dependency Manager → Android Resolver → Settings).

5. Then run Assets → External Dependency Manager → Android Resolver and press Resolve or Force Resolve.

6. As a result, the modules, that are required for Appodeal SDK work, will be imported to project's mainTemplate.gradle file.

Configure AndroidManifest.xml

Before making changes to the AndroidManifest.xml file, make sure to remove the line below:
<!-- GENERATED BY UNITY. REMOVE THIS COMMENT TO PREVENT OVERWRITING WHEN EXPORTING AGAIN-->

We distinguish 2 sets of permissions: required permissions, that are obligatory for the correct work of Appodeal SDK, and optional permissions, that can be used for better targeting. For more information about the purpose of each of the permissions, see this FAQ section.

  • These are the required permissions

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

  • These are the optional permissions

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.VIBRATE" />

Required permissions are already added to the project by Appodeal Unity Plugin. If you want to use any of the optional permissions, add them by following one of the methods listed below.

Open  Appodeal → Appodeal Settings window in Unity top bar menu. Tick all the optional permissions you want.

 

Some networks and 3rd party dependencies (related to network dependencies) can include their own permissions to the manifest. If you want to force remove such permissions you can refer to this guide.

According to  Google policy, location permissions may only be requested to provide features beneficial to the user and relevant to the core functionality of the app. You cannot request access to location data for the sole purpose of advertising or analytics.


If you are not using location for the main functions of your app

  • Remove location permission in your app by adding the following code to AndroidManifest.xml located by the path Assets/Plugins/Android and under the <manifest> tag.
<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.unity3d.player" xmlns:tools="http://schemas.android.com/tools">
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"
	tools:node="remove" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"
	tools:node="remove" />
</manifest>
  • Update the app on Google Play. During the publishing process, make sure there are no location warnings in Google Play Console.

If you are using location for the main functions of your app

  • Fill out the Location permissions declaration form in  Google Play Console . You can read more about the declaration form here .
  • Update the app on Google Play. During the publishing process, make sure there are no location warnings in Google Play Console.

Multidex Support

  • If you are using Unity 2019.2 and versions below you need to add Multidex support to your project. Follow this guide to add Multidex.

  • If you are using Unity 2019.3 or higher go to Player Settings → Publishing Settings → Other Settings and change Minimum API Level to 21 or higher.

Make sure to add Privacy Policy to your app on Google Play that links to  Appodeal's Privacy Policy  to avoid violating  Google Play Developer Distribution Agreement.

iOS Configuration

External Dependency Manager

Turn off "Link frameworks statically" option following the path Assets -> External Dependency Manager -> iOS Resolver -> Settings -> Link frameworks statically - OFF

Add SKAdNetworkIds

Ad networks used in Appodeal mediation support conversion tracking using Apple's SKAdNetwork , which means ad networks are able to attribute an app install even when IDFA is unavailable. To enable this functionality, you will need to update the SKAdNetworkItems key with an additional dictionary in your  Info.plist . 

Open  Appodeal → Appodeal Settings window in Unity top bar menu. Tick the corresponding checkbox.


Configure App Transport Security Settings

In order to serve ads, the SDK requires you to allow arbitrary loads. Set up NSAppTransportSecurity key to allow arbitrary loads following the steps:

Open  Appodeal → Appodeal Settings window in Unity top bar menu. Tick the corresponding checkbox.

 

Other feature usage descriptions

To improve ad performance the the following entries may be added:

  1. NSUserTrackingUsageDescription - As of iOS 14 using IDFA requires permission from the user. The following entry must be added in order to improve ad performance.
  2. NSLocationWhenInUseUsageDescription - Entry is required if your application allows Appodeal SDK to use location data.
  3. NSCalendarsUsageDescription - Recommended by some ad networks.

Open  Appodeal → Appodeal Settings window in Unity top bar menu. Tick the corresponding checkboxes.

 

Known issues

1. AdColony presentation issue

AdColony always checks, if the key window’s rootViewController matches the passed rootViewController. Otherwise, Adcolony fails to present the ad. If your app has multiple independent windows, you can get a message with this or similar text:

AdColony [*** ERROR ***] : AdColony has ads, but could not display them. AdColony was unable to find the currently visible UIViewController for your app. Please ensure that your key UIWindow has a rootViewController.

It means, that the rootViewController that was used in showAd, doesn't belong to the first window in the array. 

Admob Configuration 

iOS Only

Please note, if you have removed the Admob adapter, don't forget to remove the BDMNotsyAdapter as well using this guide.

Only if you use AdMob adapter.

AdMob App ID is the unique ID assigned to your app. 

To find the AdMob App ID in your AdMob account, go to Apps → your application → app settings and copy the AdMob App ID. 


Add AdMob App Ids from the Unity Menu bar Appodeal → Appodeal Settings tool for each platform. 



For more information about Admob sync check out our Admob connection guide.

Initialize SDK

Before loading and displaying ads, you need to initialize Appodeal SDK, as follows:

Import Namespaces

using AppodealStack.Monetization.Api;
using AppodealStack.Monetization.Common;

Add Lines In Code

Add the following сode to  Start() method of your main scene’s MonoBehavior  

private void Start() 
{ 
	int adTypes = AppodealAdType.Interstitial | AppodealAdType.Banner | AppodealAdType.RewardedVideo | AppodealAdType.Mrec; 
	string appKey = "YOUR_APPODEAL_APP_KEY";
	AppodealCallbacks.Sdk.OnInitialized += OnInitializationFinished;
	Appodeal.Initialize(appKey, adTypes); 
} 
... 
#region Initialization Callback
public void OnInitializationFinished(object sender, SdkInitializedEventArgs e)
{
	Debug.Log("Initialization Finished");   
}
#endregion


Make sure to replace "YOUR_APPODEAL_APP_KEY" with the actual app key.

Use the type codes below to set the preferred ad format:

  • AppodealAdType.Interstitial for interstitial.
  • AppodealAdType.RewardedVideo for rewarded videos.
  • AppodealAdType.Banner for banners.
  • AppodealAdType.Mrec for 300*250 banners.

Please note:

Ad types can be combined using "|" operator. For example, AppodealAdType.Interstitial | AppodealAdType.RewardedVideo.

Initialize only those ad types you want to use in your app to avoid getting ad requests to unused ones.

Configure Ad Types

For completing implementation integrate showing of ad types to your application.

Full-screen ad that engages users with a captivating video.


User-initiated ads where users can earn in-app rewards in exchange for viewing a video ad.


Traditional ad format that neatly places a small ad at the top or bottom of the screen.


Medium-size ads that appear within in-app content the same as banner ads.