Project Integration

• For supported Android versions, please consult the release notes.
• Within this repository you will also find our Showcase App as source code and ready built APK. Consider to check out the sources as reference for your own integration.

There are two possible ways of integrating AATKit- either using Maven distribution, or by downloading the distribution package manually and using the .aar files included. For ease of integration and further updates, we recommend using the Maven distribution.

Maven integration (click for details)

General integration instructions

Set the project's Target Compatibility to 1.8

AATKit requires Java 1.8, to make the project compile properly you need to set your project's Target Compatibility to 1.8. See here for more instructions.

Use AndroidX

AATKit requires AndroidX instead of old support libraries. Please visit the "Migrating to AndroidX" page for migration instructions.

Google Ads SDK

Google requires publishers to add their AppKey to their manifest. The AppKey can either be found within AdManager or AdMob account. Please refer to chapter Google Ads - AdMob app key for more details.

Known problems with Android Pie (Android 9) and newer

There are some known problems happening on Android Pie when the app is build targeting the SDK version 28 and above (targetSdkVersion 28):

• Some ad networks might not work correctly because of cleartext HTTP traffic being disabled by default in Android 9. To make them work you need to enable cleartext traffic, for example by adding declaration in Manifest.xml like:

<?xml version="1.0" encoding="utf-8"?>
<manifest ...>
    ...
    <application
        ...
        android:usesCleartextTraffic="true"
        ...>
        ...
    </application>
</manifest>

(Optional) Set location permissions in AndroidManifest.xml

#!java
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

The location permissions are not obligatory, but they enable better ad targeting.

Define your application name in AndroidManifest.xml

#!java
<application
        android:name="MyApplication"
        android:label="@string/app_name"
        android:theme="@style/AppTheme" >
        <activity
            android:name="MyActivity"
    ...

Initialize AATKit in MyApplication.onCreate() method.

#!java
public class MyApplication extends Application {

    public void onCreate() {
        super.onCreate();
        AATKitConfiguration configuration = new AATKitConfiguration(this);
        configuration.setDelegate(this);

        AATKit.init(configuration);
    }

}

Note

By default initialising AATKit will also enable so called shake-debug screen - special dialog with debugging information (like AATKit version and loaded ads) - after shaking the device. If you would like to disable this screen (for example when your application is a accelerometer controlled game), you can disable it in AATKitConfiguration, with code becoming:

#!java
public class MyApplication extends Application {

    public void onCreate() {
        super.onCreate();
        AATKitConfiguration configuration = new AATKitConfiguration(this);
        configuration.setDelegate(this);
        configuration.setUseDebugShake(false);

        AATKit.init(configuration);
    }

}

Notify AATKit about MyActivity events

#!java
public class MyActivity extends Activity {

    @Override
    protected void onResume() {
        super.onResume();
        AATKit.onActivityResume(this);
    }

    @Override
    protected void onPause() {
        AATKit.onActivityPause(this);
        super.onPause();
    }

}

GDPR - General Data Protection Regulation (click for details)

Integrating ads

Banner ads

Sticky banner

Sticky banner is a type of banner ad (typically 320x50) that has got fixed position on the screen, e.g. at the bottom, below the app content. It might get refreshed with a new impression in a fixed interval (e.g. every 30 seconds). AATKit provides an API dedicated to this type of banner - see here.

In-feed banner

In-feed banner is a type of banner (typically medimum rectangle 300x250) that is bound to a scrollable feed and moving with the feed of content. AATKit provides another API dedicated to this type of banner - see here.

Special banner integrations

• Using MultiSize banner placement
• Using In-Feed banner placement without caching

Fullscreen ads (click for details)

Rewarded video ads (click for details)

Native ads (click for details)

AppOpen ads (click for details)

AATKit callbacks

The AATKit.Delegate interface provides the following callbacks:

• void aatkitHaveAd(int placementId) - Notifies that placement has finished loading an ad successfully.

• void aatkitNoAd(int placementId) - Notifies that placement has failed to load an ad.

• void aatkitPauseForAd(int placementId) - Notifies that ad went fullscreen and that application should pause.

• void aatkitResumeAfterAd(int placementId) - Notifies that ad came back from fullscreen and that application should resume.

• void aatkitShowingEmpty(int placementId) - Notifies that placement has loaded a special Empty ad.

• void aatkitUserEarnedIncentive(int placementId, @Nullable AATKitReward aatKitReward) - Notifies that placement has earned incentive (from rewarded video ads). The aatKitReward parameter informs about the reward earned. Please note that not all networks provide this information, and this parameter can be null. Note: This callback might also be invoked for regular fullscreen placements, not just the ones configured for rewarded videos. Please make sure placementId is your rewarded video placement before rewarding the user.

• void aatkitObtainedAdRules(boolean fromTheServer) - Notifies that the AATKit has obtained ad rules. The parameter fromTheServer indicates if the rules came from the server. It will be false if the currently used rules come from the setInitialRules(String) method or the cached rules are used.

• void aatkitUnknownBundleId() - Notifies that application's bundle ID was not recognized by the AddApptr server.

• void aatkitHaveAdForPlacementWithBannerView(int placementId, BannerPlacementLayout bannerView) - Notifies that AATKit has new banner view ready for placement. Used only for MultiSizeBanner.

• void aatkitHaveVASTAd(int placementId, VASTAdData data) - Notifies that AATKit has new VAST ad ready for placement.

To use them, you will have to implement the AATKit.Delegate and pass it when initialising the AATKit.

Ad network specific information:

Google Ads

Google requires their app-ID to be declared in the manifest. Please follow these instructions. In order to get the Google app-ID for you app, either find it within your own AdMob or AdManager account or contact our support.

If your app shall not use AdMob but just AdManager (which will be an extreme exception), you don't need to declare the AdMob app-ID, but instead declare, that your app is an "AdManager app". Please follow these instructions.

Callback limitations

Unity ads

• From AATKit 2.25.18 Unity Ads will load only non-personalized ads if there is no consent information specified.
• The incentive callback is called every time the full video is watched by the user, even for non-rewarded placements. It is required to use placementId passed as parameter to decide if the user should be rewarded.
• Unity SDK doesn't provide click notifications, so user clicks will not be visible in AddApptr reporting panel.

Ogury

• Ogury does not provide click notifications, so user clicks will not be visible in AddApptr reporting panel.

Ad network special features

AppLovinMAX

It is highly recommended to enable AppLovin Ad Review. Please follow AppLovin's instructions regarding the .gradle configuration additions. The rest (SDK init etc.) will be handle by AddApptr's SDK as usual.
If you are using AppLovin through AddApptr's AppLovin account, you need to use 1Tpoa041koqEJfUi7aGU6LUO6wUNkt3RDPdQsHUzFqK1NPxT1zOXzfQnOOvg9I4DxRi9hfH4tIR_kQGX0A2XI0 as Ad Review key.

AppNexus

Autoclosing fullscreen ads

To use this feature, add meta-data node to your manifest like:

<meta-data android:name="com.intentsoftware.addapptr.appnexus_autoclose_delay" android:value="5"/>

Native banner content

To enable native banner content for AppNexus, add meta-data to AndroidManifest like:

<meta-data android:name="com.intentsoftware.addapptr.use_appnexus_native_banners" android:value="true"/>

FeedAd

Shutter colour

To use specific shutter colour, add meta-data to AndroidManifest like:

<meta-data android:name="com.intentsoftware.addapptr.feedad_shutter_colour" android:value="#000000"/>

Disable spinner

To disable FeedAd banner spinner, add meta-data to AndroidManifest like:

<meta-data android:name="com.intentsoftware.addapptr.feedad_disable_spinner" android:value="true"/>

PubNative

Set minimum amount of seconds until the HTML can be skipped for PubNative fullscreen.

To use this feature, add meta-data to AndroidManifest like:

<meta-data android:name="com.intentsoftware.addapptr.pubnative_offset_secs_HTML_Interstitial" android:value="5"/>

Set minimum amount of seconds until the video can be skipped for PubNative fullscreen.

To use this feature, add meta-data to AndroidManifest like:

<meta-data android:name="com.intentsoftware.addapptr.pubnative_offset_secs_video_interstitial" android:value="10"/>

Defaults

If the offsets are not set in Manifest, default offset of 5s will be used for both HTML and Video PubNative ads.

Advanced instructions

Enabling/disabling use of location data

By default, sending of location data is disabled. To change this setting, use new method available in both AATKitConfiguration and AATKitRuntimeConfiguration:

Code sample:

#!java
AATKitRuntimeConfiguration newConfiguration = new AATKitRuntimeConfiguration();
newConfiguration.setUseGeoLocation(true);
AATKit.reconfigure(newConfiguration);

Skipping of networks without TCF2 consent

When requesting ads, AATKit can check the TCF2 consent state for given networks (as long as TCF2-compatibile CMP is used), and skip the ones without consent. This feature is disabled by default, to enable it use the setShouldSkipRules method in AATKitConfiguration, like

#!java
    public void onCreate() {
        super.onCreate();
        AATKitConfiguration configuration = new AATKitConfiguration(this);
        configuration.setDelegate(this);
        configuration.setShouldSkipRules(true);

        AATKit.init(configuration);
    }

Default list of networks to be skipped

By default, the following ad networks will be skipped when they have no consent and rule skipping is enabled:

• Digital Turbine (ADCOLONY)
• Admob
• AdX
• Amazon HB
• Xandr (APPNEXUS)
• Criteo SDK
• Google AdManager (DFP)
• Google AdManager (Direct) (DFPDIRECT)
• Inmobi
• Ogury
• Verve (PUBNATIVE)
• Magnite (RUBICON)
• smaato
• Teads
• Equativ (SMARTAD)
• Equativ (Direct) (SMARTADSERVERDIRECT)
• YOC
• FeedAd

Modifying list of networks to be skipped

If rule skipping is enabled, by default AATKit will use the above default set of networks to be skipped if they have no consent. To change this default set and skip rules only for specific ad networks:

    public void onCreate() {
        super.onCreate();
        AATKitConfiguration configuration = new AATKitConfiguration(this);
        configuration.setShouldSkipRules(true);
        Consent consent = new SimpleConsent(NonIABConsent.OBTAINED);
        // Skip rules only for SmartAd and Smaato
        Set<AdNetwork> networksToBeSkipped = new HashSet<>();
        networksToBeSkipped.add(AdNetwork.SMARTAD);
        networksToBeSkipped.add(AdNetwork.SMAATO);
        consent.setNoConsentNetworkStopSet(networksToBeSkipped);
        configuration.setConsent(consent);
        AATKit.init(configuration);
    }

Keyword targeting

To pass keyword targeting to ad networks, please use the following methods:

• AATKit.setTargetingInfo(Map<String, List<String>> info) - Sets the targeting information for the application. Accepts targeting information in the form of key-list of values map. It will only be used for placements without special targeting information specified.

• AATKit.setTargetingInfo(int placementId, Map<String, List<String>> info) - Sets the targeting information for the given placement. Overrides general targeting information set for application.

• AATKit.addAdNetworkForKeywordTargeting(AdNetwork network) - Adds an ad network to the list of ad networks that would receive targeting keywords (if any set). If no ad networks are added, any set keywords will be delivered to all ad networks supporting keyword targeting.

• AATKit.removeAdNetworkForKeywordTargeting(AdNetwork network) - Removes an ad network from the list of ad networks that receive targeting keywords (if any set). If no ad networks are added to the list, any set keywords will be delivered to all ad networks supporting keyword targeting.

In addition to keyword targeting, AdMob, AdX, DFP and Bluestack support Content Targeting URL. You can utilize this feature by using the following methods:

• AATKit.setContentTargetingUrl(String targetingUrl) - Sets the targeting URL for the application. It will only be used for placements without special targeting URL information specified.

• AATKit.setContentTargetingUrl(int placementId, String targetingUrl) - Sets the targeting URL for the given placement. Overrides general targeting URL set for application.

Be aware that when using the newer banner APIs, i.e. In-feed banner or BannerCache, these global settings will not be used, but both keyword targeting and/or content targeting URL have to be set for the BannerRequest object (see here).

Frequency capping

Please find the documentation about frequency capping here

Using test ads

In order to test your application using demo ads, set the testId in AATKitConfiguration like:

#!java
    public void onCreate() {
        super.onCreate();
        AATKitConfiguration configuration = new AATKitConfiguration(this);
        configuration.setDelegate(this);
        configuration.setTestModeAccountId(testId);

        AATKit.init(configuration);
    }

The AddApptr SDK identifies your app using the bundle id from the Android app store. For the identification to work properly, it is important to disable the test-mode when going public with your app. No further IDs need to be set in the source code of your app! Our rule server takes a look at your bundle ID and decides according to the rules which ads you get delivered.

Remember to disable test mode before submitting your application!

Listening for statistics events

To get informed about statistics reporting events, implement the StatisticsListener:

        /**
         * Notifies that an adspace has been counted.
         */
        void countedAdSpace();

        /**
         * Notifies that an request has been counted for a given network.
         *
         * @param network Network for which the request has been counted.
         */
        void countedRequest(AdNetwork network);

        /**
         * Notifies that an response has been counted for a given network.
         *
         * @param network Network for which the response has been counted.
         */
        void countedResponse(AdNetwork network);

        /**
         * Notifies that an impression has been counted for a given network.
         *
         * @param network Network for which the impression has been counted.
         */
        void countedImpression(AdNetwork network);

        /**
         * Notifies that an viewable impression has been counted for a given network.
         *
         * @param network Network for which the viewable impression has been counted.
         */
        void countedVimpression(AdNetwork network);

        /**
         * Notifies that an click has been counted for a given network.
         *
         * @param network Network for which the click has been counted.
         */
        void countedClick(AdNetwork network);

bannerPlacementId = AATKit.createPlacement("Banner", PlacementSize.Banner320x53, yourStatisticsListener);

Impression level information

You can set an optional impression listener for each placement. For each impression counted by AddApptr, the listener will be informed about impression details like banner size, ad network, network key, mediation type, if the impression comes from a direct deal, and price (currency: MAYO=EUR, Auction=USD, Waterfall=price not available).

To use it with AATKit 3:

yourPlacement.setImpressionListener(impressionListener);

Code example:

        bannerPlacement.setImpressionListener(new ImpressionListener() {
            @Override
            public void didCountImpression(@NonNull AATKitImpression impression) {
                String networkName = impression.getAdNetworkName();
                double impressionPrice = impression.getPrice();
                Log.d("IMPRESSION_INFO", "Counted impression from: " + networkName + ", price:" + impressionPrice);
            }
        });

Obtaining debug logs

If you would want to obtain more debug logs from AATKit, paste the following line:

adb shell setprop log.tag.AATKit VERBOSE

Checking availability of Google Play Services

As most networks rely on Google Play Services, it is also advised to check if required version of Google Play Services is available on device and display a dialog if update is needed. It can be done in onResume method of your main activity, for example like:

#!java

    @Override
    protected void onResume() {
        super.onResume();

        if (GoogleApiAvailability.getInstance().isGooglePlayServicesAvailable(this) != ConnectionResult.SUCCESS) {
            Dialog d = GoogleApiAvailability.getInstance().getErrorDialog(this,
                    GoogleApiAvailability.getInstance().isGooglePlayServicesAvailable(this), 4);
            d.show();
        }

        AATKit.onActivityResume(this);
    }

Proguard

• All necessary Proguard configurations are included in our distribution packages. There is no need to add anything into Proguard configuration manually.

Disabling ad networks at runtime

If you would like to disable some network at runtime, you can do so by just calling the following method:

#!java
AATKit.setNetworkEnabled(network, false);

Of course, the network can be re-enabled by calling

#!java
AATKit.setNetworkEnabled(network, true);

Detecting best banner sizes

Detecting maximum banner width on device

For your convenience, we have added methods for detecting maximum banner width on given device:

• AATKit.maximumBannerSizePortrait(Context context)
• AATKit.maximumBannerSizeLandscape(Context context)

They can be used for placement creation, like:

bannerPlacementId = AATKit.createPlacement("Banner", AATKit.maximumBannerSizePortrait(this));

Detecting all banner sizes fitting on device

Similarly to methods for detecting of maximum banner width, we have also added methods returning a set of fitting banner sizes on given device:

• AATKit.fittingBannerSizesPortrait(Context context)
• AATKit.fittingBannerSizesLandscape(Context context)

They can be used for limiting allowed banner sizes for banner request, like:

BannerRequest request = new BannerRequest(null);
request.setBannerSizes(AATKit.fittingBannerSizesPortrait(this));

Dealing with 65K method limit problem

In bigger application, you may encounter the following problem when building your application:

Conversion to Dalvik format failed:
Unable to execute dex: method ID not in [0, 0xffff]: 65536

trouble writing output:
Too many field references: 131000; max is 65536.
You may try using --multi-dex option.

Size of AATKit within your application

In order to see how much space the AATKit will take up in your app, you can consult the following table (based on AndroidStudio integration):

Explanation:

• The raw app corresponds to application without AATKit.
• "app + AATKit + required parts of Google Play Services" has only raw AATKit library without any network SDKs (other than AdMob, AdX and DFP- integrated into Google Play Services).
• The app wth all network SDKs uses MultiDex.
• final .apk is the generated and signed application package.

Showcase app apk

You can download the prebuild showcase app apk here.

Samples

• See The code of our showcase project to learn more about AATKit integration.