SDK Integration | Appodeal Intelligent Ad Mediation

App key

Link your Admob account

Appodeal yields optimal results in cooperation with Admob. To continue, you need to link your Admob account.

If you don't have Admob account, please sign up on Admob.com.

To link your Admob account to Appodeal, use the Chrome extension:

INSTALL EXTENSION


The extension source code is available at https://github.com/appodeal/admob-configurator.

The extension will make two changes in your Admob account. First, it will allow Appodeal to access your Admob reports over API, and second, it will create new ad units on Admob and submit them to Appodeal.

VIDEO TUTORIAL

Get Started

  • Use Unity 4.6.8+
  • Target Android OS 4.0+ and iOS 8.0+

You still can integrate the Appodeal SDK into a project with a lower value of minimum iOS version. On the devices that don’t support iOS 8.0+, our SDK will be disabled.

Download SDK

The Appodeal Unity plugin 2.8.42 includes the newest beta Appodeal SDK 2.4.2 with major native ads improvements, segment v2 support, GDPR compliance and Parallel bidding support. To download it click the button below:

Download Appodeal-Unity-2.8.42

For Android-based projects: If you are using newer Unity versions with the Gradle build system or plan to export your project to Android Studio, enable MultiDex according to this documentation and use this plugin:

Download Appodeal-Unity-2.8.42 nodex

General Data Protection Regulation (GDPR) compliance

Publishers need to update their apps to collect user consent prior to initializing our SDK (Read our guide on collecting consent here). Publisher need to pass boolean consent flag(with 'false' meaning that user declined to give consent) to Appodeal.initialize() method in our SDK.

Import the Appodeal Unity plugin

Open your project in the Unity Editor. Go to Assets → Import Package → Custom package and select the downloaded *.unityPackage file. Select all the files and press Import.  

Integrate SDK

Android configuration

The Appodeal Unity Plugin contains Google's Play Services Resolver, which helps to avoid compatibility issues with other plugins. To use it, follow these steps:

1. In the Unity editor select File → Build Settings → Android.

2. Then run Assets → Play Services Resolver → Android Resolver and press Resolve Client Jars.

As a result, modules, which are required for the Appodeal SDK support, will be imported into your project. You can edit them or add other modules in the Assets/PlayServicesResolver/Editor/AppodealDependencies.cs file.

You should also replace ${applicationId} in the Assets/Plugins/Android/appodeal/AndroidManifest.xml for nodex build or in file Assets/Plugins/Android/ogury/AndroidManifest.xml for all build with your App Bundle ID.

E.g.:

All the required AndroidManifest.xml tags are already added to the Appodeal Unity Plugin. If you don't want to use optional permissions, go to Plugins → Android → Appodeal, open AndroidManifest.xml and remove them from there.

If you are not using location services in your app or any other SDK that require location permissions, add the following code to the Androidmanifest.xml file. It will make your app available on devices that don't have GPS support:

iOS configuration

No additional steps are required to include the Appodeal SDK into an iOS-based project.

Initialize SDK

Before starting to load ads, you need to initialize the Appodeal SDK, as follows:

1. Import the namespaces:

2. Add the following code within the Start() method of your main scene’s MonoBehavior:

E.g.: 

Choose ad formats

The adTypes parameter in the code above is responsible for the ad formats you are going to implement into your app. To combine them, use the operator |.

Appodeal supports all major mobile ad formats:

  • Interstitial (Appodeal.INTERSTITIAL): full-screen ads, that contain a static image or a skippable video.
  • Banner (Appodeal.BANNER): rectangular ads that occupy a spot within an app's layout. Appodeal.BANNER_VIEW is a banner ad with the custom position: you can move it along the axis.
  • Rewarded video (Appodeal.REWARDED_VIDEO): non-skippable video ads that users may choose to watch to get a reward.
  • Non-skippable video (Appodeal.NON_SKIPPABLE_VIDEO): video ads that must be watched until the end. This format is an alias of Appodeal.REWARDED_VIDEO.
  • Native ads: ads that imitate the structure and style of an app. This ad format is not available for the Unity-based projects.

Note: Non-skippable and rewarded videos cannot be used simultaneously. If you are not sure, which ad formats would suit you the best, check out our FAQ.

Implement an interstitial

7.2.1 Show an interstitial

This method returns a boolean value indicating whether the show call was passed to the appropriate SDK. 

7.2.2 Check if an interstitial is loaded

We highly recommend using this method before showing an ad, to ensure that it was entirely loaded and will be displayed correctly. 

7.2.3 Set interstitial callbacks (only for Unity 4.2+)

The callbacks are used to track different events in the lifecycle of an ad, e.g. when an ad was clicked on or closed. To implement them, you need to follow three steps:

1. Extend your public class with IInterstitialAdListener:

2. Then call the following method:

3. Now you can use the following callback methods within your public class:

Implement a rewarded video

7.3.1. Show a rewarded video

7.3.2. Check if a rewarded video is loaded

We highly recommend using this method before showing an ad, to ensure that it was entirely loaded and will be displayed correctly. 

7.3.3. Get reward data for a specific placement

To get reward data and notify your users of it before the video ad is shown, use this method. It returns KeyValuePair with the currency type and amount of the reward.

7.3.4. Set rewarded video callbacks 

The callbacks are used to track different events in the lifecycle of an ad, e.g. when an ad was clicked on or closed. To implement them, you need to follow three steps:

1. Extend your public class with IRewardedVideoAdListener:

2. Then call the following method:

3. Now you can use the following callback methods within your public class:

7.3.5. Server-to-server (S2S) rewarded video callbacks

The S2S callbacks are used to reward users with virtual currency or in-game items and help prevent cheating. When a user watches a rewarded video ad, a callback is sent to the specified URL on your server. It provides all information about the type of reward and the user you need to grant the reward to. You need to validate this information and adjust user balance accordingly.

1. On your server construct the URL that will receive the callbacks.

2. Go to your Appodeal Dashboard and enter the created URL and the encryption key in App Settings.

3. The S2S callbacks will be sent to your URL using GET requests with two parameters:

4. Use the following sample scripts to let your URL decrypt the data and validate it. If you need scripts in other languages, contact our support team, and we will gladly provide you with them.

Sample in PHP: reward.php

Sample in Ruby: reward.rb

Sample in Java: reward.java

Sample in Node.js: reward.js

Sample in Python 3: reward.py

5. Check impression_id for uniqueness and store it in your system to prevent duplicate transactions.

To set user ID run the following code before the SDK initialization:

Implement a non-skippable video

7.4.1. Show a non-skippable video

7.4.2. Check if a non-skippable video is loaded

7.4.3. Set non-skippable video callbacks (only for Unity 4.2+)

The callbacks are used to track different events in the lifecycle of an ad, e.g. when an ad was clicked on or closed. To implement them, you need to follow three steps:

1. Extend your public class with INonSkippableVideoAdListener:

2. Then call the following method:

3. Now you can use the following callback methods within your public class:

Implement a banner

7.5.1. Show a banner at the bottom of the screen

7.5.2. Show a banner at the top of the screen

7.5.3. Check if a banner is loaded

We highly recommend using this method before showing an ad, to ensure that it was entirely loaded and will be displayed correctly.

7.5.4. Hide a banner

7.5.5. Screen rotation

The screen rotation always recreates the Unity activity, which may cause a banner disappearing. To prevent that, add the following code within the OnApplicationFocus() method of your MonoBehaviour:

7.5.6. Show a banner with a custom position

Appodeal.BANNER_VIEW is a banner ad which you can move along the axis to the position you choose. To use it you should first initialize the Appodeal Unity SDK with the Appodeal.BANNER_VIEW ad format.

To show Appodeal.BANNER_VIEW use the following code:

For xPosition and yPosition use custom int value or constants:

  • Appodeal.BANNER_HORIZONTAL_SMART — to use the full-screen width;
  • Appodeal.BANNER_HORIZONTAL_CENTER — to center a banner horizontally;
  • Appodeal.BANNER_HORIZONTAL_RIGHT — to align a banner to the right;
  • Appodeal.BANNER_HORIZONTAL_LEFT — to align a banner to the left;
  • Appodeal.BANNER_TOP — to align a banner to the top of the screen;
  • Appodeal.BANNER_BOTTOM — to align a banner to the bottom of the screen.

To set your custom width and height, you can use the constants of The Unity’s Screen.currentResolution.width and Screen.currentResolution.height with a constant value.

To hide Appodeal.BANNER_VIEW use the following code:

Note: If your app supports screen rotation, you need to call Appodeal.showBannerView every time, when screen orientation changes.

7.5.7. Set banner callbacks (only for Unity 4.2+)

The callbacks are used to track different events in the lifecycle of an ad, e.g. when an ad was clicked on or closed. To implement them, you need to follow three steps:

1. Extend your public class with IBannerAdListener:

2. Then call the following method:

3. Now you can use the following callback methods within your public class:

7.5.8. Enable 728x90 banners

7.5.9. Disable banner refresh animation

7.5.10. Disable banner background

7.5.11. Smart banners

Smart banners are the banner ads which automatically fit the screen size. Using them helps to deal with the increasing fragmentation of the screen sizes on different devices. In the Appodeal SDK the smart banners are enabled by default. To disable them, use the following method:

Advanced features

7.6.1. Enable test mode

In the test mode only test ads will be shown with the 100% fill rate. Your debug data will be written to Logcat.

7.6.2. Enable logging

Available parameters:

  • Appodeal.LogLevel.None - logs off;
  • Appodeal.LogLevel.Debug - debug messages;
  • Appodeal.LogLevel.Verbose - all SDK messages.

To search for the additional logs, use the tag Appodeal

7.6.3. Check if a loaded ad is precache

Pre-caching allows loading ads in the background of the app, which helps to show them to users without any delay. In Appodeal this kind of ads is called precache and is currently supported only for the interstitials and banners. To check if an ad is a precache, use the following method:

E.g.:

7.6.4. Enable manual ad caching

1. Disable automatic caching before the SDK initialization:

2. Then turn on the manual caching, using the following method:

E.g.:

7.6.5. Enable automatic ad caching

Use this method before the SDK initialization:

E.g.:

7.6.6.Set onLoaded callback for precache ads

This method is currently supported only for the interstitials and banners. Use it before the SDK initialization.

To trigger the callback only when a not precache ad is loaded use the following code:

To trigger the callback when both precache and not precache a loaded, use the following code. In this case, the callback will trigger twice:

7.6.7. Disable data collection for kids apps

7.6.8. Disable ad networks

To disable the networks you don’t want to get ads from, use the following method before the SDK initialization:

To disable networks for the specific ad formats use the following method before the SDK initialization:

Available parameters: adcolony, admob, amazon_ads, applovin, appnext, avocarrot, chartboost, facebook, flurry, inmobi, inner-active, ironsource, mailru, mmedia, mopub, ogury, openx, pubnative, smaato, startapp, tapjoy, unity_ads, vungle, yandex.

7.6.9. Disable checking for location permission

To disable toast-messages, if ACCESS_COARSE_LOCATION permission is missing, use the following method before the SDK initialization:

7.6.10. Disable checking for permission to write in the external storage

To disable toast-messages, when the WRITE_EXTERNAL_STORAGE permission is missing, use the following method before the SDK initialization:

Note: Disabling of all the networks that need this permission may lead to low fill rate for the video ads.

7.6.11. Requesting runtime permissions in Android Marshmallow (API 6.0+)

1. Extend your public class with IPermissionGrantedListener:

2. Call the following method within the Awake() method of the class that loads first:

3. Now you can use the following callbacks to operate with answers on requesting WRITE_EXTERNAL_STORAGE and ACCESS_COARSE_LOCATION permissions in Android Marshmallow and higher:

7.6.12. Track in-app purchases

This method tracks all of your in-app purchases and sends information for analytics to our server:

E.g.:

7.6.13. Test the third-party networks adapters integration

To check integration of the third-party networks, you need to start a test screen by calling the following method. It is currently supported only for the Android:

7.6.14. Mute video ads

If calls are muted on a user’s device, you can also mute sound of video ads for them, using the following method:

Transfer User Data

Our SDK provides the transfer of user data for better ad targeting and higher eCPM. This feature allows targeting users by their age and gender. Both of the parameters are optional.

To obtain a reference to the user settings, please call this method before the SDK initialization:

2. Set the int value for the age parameter, e.g.:

3. Specify the user’s gender. Possible values: UserSettings.Gender.FEMALE, UserSettings.Gender.MALE, UserSettings.Gender.OTHER. E.g.:

Segments and Placements

Segments

A segment is a fraction of audience unified by filters: e.g., by gender, age or any other parameter known to the app and directed to the Appodeal SDK. Segments are used to track statistics for various user categories and to manage ads for these categories.

If you have no segments, all users will be matched to "default" segment.

If you have multiple segments, pay attention to their order. Only the first segment, in which filters are matched to the user, will apply. All of the rest will be ignored.

To create a segment, follow these steps:

1. Go to our Dashboard, select Segments and click Add new.

2. Use one of the presets or click New Segment, if you want to create a blank segment without any default settings.

3. Fill in a name for your segment.

4. Define the filters. You can select as many of them as you want:

General filters

Age - group users of a particular age;

Applications - group users of one or multiple of your apps;

Country - group users from particular countries;

Device Type - group users that use tablet or/and phone;

Gender - group users by their gender.

Advanced filters

App Version - group users that use a particular app version;

Average Session Length - group users that spend a particular period of time in your app in average;

Bought In-Apps - group users who did or did not make the in-app purchases. Only counts the purchases tracked by the Appodeal.trackInAppPurchase() method;

Connection Type - group users by their connection type: Wi-Fi, Mobile Internet or other;

In-Apps Amount - group users by number of the in-app purchases they’ve made. Only counts the purchases tracked by the Appodeal.trackInAppPurchase() method;

OS Version - group users by their OS version;

Part of Audience - group a particular percentage of the users. This filter is useful when testing ad campaigns, A/B testing or monetization testing in general;

SDK Version - group users with a particular version of the Appodeal SDK;

Session Count - group users who’ve run the app the particular number of times;

Session Time - group users who run the app at a particular time of day or on a particular day of the week. The segment is aimed at users’ local time and their time zone.

Manual filters

Manual Filters allow grouping users by any characteristics you choose. E.g. you can select users by the source that directed them to you or by the number of levels they’ve played in your game.

To use the manual filters, fill in a name and a value for it. The value can be boolean, numeric or string-based.

5. Select the settings for your new segment:

Disable Ad Types. If any of the ad formats affect negatively a particular part of your audience, you can disable them for this segment;

Disable Ad Networks. If any of the ad networks affect negatively a particular part of your audience, you can disable them for this segment completely or choose the specific ad formats that will be not loaded from this ad network;

Min Pricefloor, $. Allows to set a minimum price for 1000 impressions for every ad format.

Overriden eCPM, $. Allows to manage manually the position of each ad format for every ad network inside the waterfall.

6. Click Create Segment and then enable it in the segments list.

Placements

Appodeal SDK allows you to choose different placements for each impression. Your revenue is separated by placement in our dashboard, which helps to analyze what kind of ads earns you more money.

The placement can only be used as a part of the existing segment.

1. To show an ad in the specific placement, use:

2. To check if an ad can be shown in the specific placement, use:

3. To configure your impression logic for each placement, use the settings listed below:

General Settings

Disable Ad Types. Disable a specific ad format for this placement;

Disable Ads. Disable all the ads for this placement;

Interstitial Type. Show either static or video interstitials at this placement;

Min Pricefloor, $. Set a minimum price for 1000 impressions for every ad format at this placement;

Reward. Set amount and currency of a reward, users get after watching a rewarded video ad at this placement. This information will be passed in onRewardedVideoFinished() callback. To get reward data before video starts, use the Appodeal.getRewardParameters(placementName) method.

Frequency Settings

Impression Interval. Set the minimum allowed interval between full-screen ads or banners.

Impressions for Period. Set the maximum allowed number of impressions for a particular period of time for full-screen ads.

Impressions per Session. Set the maximum allowed number of impressions for full-screen ads per one session.

4. If you have no placements or call the Appodeal.show() method with a placement that doesn’t exist or without any placements in your segment, the impression will be registered to the default placement and its settings will be applied.

To get more information about segments and placements, check out our Knowledge Base.

Publish your App

Before submitting your app to the App Store or Google Play, you need to check the following settings.

For the iOS-based apps

If your app gets rejected by the App Store because of some missing usage descriptions, add those of them you need to your info.plist file:

Update your IFDA settings in order to compile with the Apple Advertising Policy:

1. Go to the Advertising Identifier section.

2. Set Yes on the right panel.

3. Tick Serve advertisements within the app and Attribute this app installation to a previously served advertisement. 

4. Tick the confirmation box under Limit Ad tracking setting in iOS.

For the Android-based apps

If you are using ProGuard, add the following code to your ProGuard configuration file:

It’s Done

You are ready to use Appodeal. If you have any questions, check out our FAQ or contact the support team.

Third-party SDKs versions

NetworkAndroid SDK versioniOS SDK version
Adcolony3.3.03.3.0
Admob12.0.07.27.0
Amazon Ads5.8.1.12.2.15.1
Applovin8.0.05.0.1
Chartboost7.2.07.2.0
Facebook Audience Network4.27.04.27.2
Flurry10.1.08.5.0
Inmobi7.1.07.1.1
IronSource6.7.66.7.9.1
MillenialMedia6.4.06.6
Mobvista8.11.03.8.0
myTarget4.7.24.7.2
Mopub4.15.04.19.0
Ogury2.1.15-
SmaatoAPI8.1.4
Startapp3.8.43.7.1
Tapjoy11.11.111.11.0
Unity Ads2.1.22.1.1
Vungle6.2.56.2.0
Yandex Mobile Ads2.622.7.2