Wiki

Overview

The aatkit plugin offers easy integration of mobile ad networks. AddApptr gives you access to all the networks with one single SDK.

To use the AddApptr SDK, please sign up for an account.

Integration instructions

Download link and unzip Marmalade extension.
In the .mkb config file of your project, include the /s3eAATKit/s3eAATKit.mkf file as a subproject to have access to the AATKit methods. If the s3eAATKit dir is in your project directory, add to your .mkb with the following line:
```
subproject s3eAATKit/s3eAATKit
```
Add to your project’s main .cpp file:
```
#include "s3eAATKit.h"
```

AATKit Marmalade 1.8.0 or later is GDPR compliance. New structure s3eAATKitConfiguration was introduced to help initializing AATKit (this is the easiest way to get default values which you should pass to the s3eAATKitInitWithConfiguration method). Using it you can inform AATKit:

If the user is subject to the GDPR laws - field bool consentRequiredCfg.
If the user has given or withheld consent for the collection and use of personal data - field int simpleConsentCfg.
- the enum values for simpleConsentCfg that should be used:
  - S3E_AATKIT_SIMPLE_CONSENT_OBTAINED if the user has given the consent.
  - S3E_AATKIT_SIMPLE_CONSENT_WITHHELD if the user has declined.

#!c++
s3eAATKitConfiguration *config = new s3eAATKitConfiguration();
config->testModeAccountIDCfg = 74;
config->consentRequiredCfg = true;
config->simpleConsentCfg = S3E_AATKIT_SIMPLE_CONSENT_OBTAINED;

s3eAATKitInitWithConfiguration(
    config->alternativeBundleIDCfg.c_str(), 
    config->initialRulesCfg.c_str(), 
    config->shouldCacheRulesCfg, 
    config->shouldReportMetricsUsingAlternativeBundleIDCfg, 
    config->testModeAccountIDCfg, 
    config->consentRequiredCfg, 
    config->simpleConsentCfg,
    config->consentAutomaticCfg, 
    config->consentStringCfg.c_str(),
    config->useGeoLocationCfg);

Removing unwanted Ad networks

If you don't want to import all ad networks to your project you can remove them by editing s3eAATKit.mkf file and removing/commenting lines of code corresponding to networks you dont't need. If you're unable to find network you want to remove it means that this network is built in aatkit and cannot be removed.

Android - using Ogury and Millennial networks

If you use Ogury and/or Millennial you should edit AATKitManifest.xml file located int the root directory of the extension. Edit attributes for provider tags. Just replace YOUR_APPLICATION_ID text by your actual application id (bundle identifier). Please note you should remove these xml tags if you are not going to use Ogury and/or Millennial networks.

#!xml

(...)
        <provider
            android:name="com.millennialmedia.internal.utils.MediaContentProvider"
            android:authorities="YOUR_APPLICATION_ID.MediaContentProvider"
            android:grantUriPermissions="true"
            android:exported="false" />
(...)
        <provider
            android:name="io.presage.provider.PresageProvider"
            android:authorities="YOUR_APPLICATION_ID.PresageProvider"
            android:enabled="true"
            android:exported="true" />
(...)

Android - using AppNexus prebid libraries

You cannot create a signed apk file with AppNexus prebid for both DFP and MoPub. This is why AppNexus prebid for MoPub is disabled by default. If you want to use AppNexus prebid for MoPub, please edit the s3eAATKit.mkf file like below:

#!
(...)
# android - APPNEXUSPREBID("AppNexusPrebid")
    # android-external-jars="aatkit/AATKit/libs/pricecheck-sdk-dfp-2.4.8.jar"
    android-external-jars="aatkit/AATKit/libs/pricecheck-sdk-mopub-2.4.8.jar"
(...)

iOS - using Inneractive and MoPub networks

These network are disabled because they cause errors when building application using the Marmalade Hub. However, you can use the Inneractive and InMobi networks if you are building your application via XCode. To enable them, edit the s3eAATKit.mkf file. You need to remove comment characters for the lines which links Inneractive and InMobi libraries. Finally the s3eAATKit.mkf file should contain these configuration:

...

# ios - MOPUB("MoPub")
    iphone-link-libdir="aat/subSDKs/MoPub_4.19.0"
    iphone-link-lib="MoPubSDK"

...

# ios - INNERACTIVE("Inneractive")
    iphone-link-libdir="aat/subSDKs/Inneractive_6.4.4"
    iphone-link-lib="InneractiveSDK"

...

Now you should be able to build your application with the working Inneractive/MoPub networks via XCode. However, when these libraries are linked, you won't be able to build your application via Marmalade Hub.

Facebook Audience Network Integration

Android

Download and unpack Facebook SDK
Go to s3eAATKit/aatkit directory and copy to it FacebookAudienceNetwork library: FacebookSDK/AudienceNetwork/bin/AudienceNetwork.jar
Edit s3eAATKit.mkf and s3eAATKit_android_java.mkb and uncomment Facebook jar path.
Rebuild android library

iOS

Download and install Facebook SDK
Open s3eAATKit.mkf file and in deployments section uncomment part coresponding to facebook framework. Make sure that defined framework path points to directory where is FacebookSDK.framework exist.
Rebuild ios library

Usage guide

Initialize AATKit

#!c++
#include "s3eAATKit.h"

void Init()
{
    s3eAATKitInit();
}

Create placements and start autoreloading

#!c++
#include "s3eAATKit.h"

const char* bannerId = "BannerPlacement";
const char* interstitialId = "FullscreenPlacement";

void Init()
{
    ...

    // banner placement
    s3eAATKitCreatePlacement(bannerId, S3E_AATKIT_BANNER_AUTO);
    s3eAATKitStartPlacementAutoReload(bannerId);

    // fullscreen placement
    s3eAATKitCreatePlacement(interstitialId, S3E_AATKIT_FULLSCREEN);
    s3eAATKitStartPlacementAutoReload(interstitialId);

    // multi size banner placement
    s3eAATKitCreatePlacement(multiSizeId, S3E_AATKIT_MULTI_SIZE_BANNER);
    s3eAATKitStartPlacementAutoReload(multiSizeId);
}

Show fullscreen placement

#!c++
s3eAATKitShowPlacement(interstitialId);

Please note that calling the method showPlacement does increase the AdSpace count, which is used to calculate the fill rate. An AdSpace expresses the intention to show an ad. To ensure correct reporting of existing AdSpaces, it is advised to call the showPlacement method each time you want to display an interstitial - no matter whether the event aatkitHaveAd occurred or not.

Rewarded videos

The integration steps for rewarded videos are very similar like for other fullscreen ads. You will just need to use S3E_AATKIT_REWARDED and give this placement some specific name, like

#!c++
s3eAATKitCreatePlacement("RewardedVideo", S3E_AATKIT_REWARDED );

If you’ve used rewarded videos before with the normal fullscreen placement, please make sure to use a different placement name for your new “Rewarded” placement. When the user watches the rewarded video and incentive is earned, the following delegate method will be called:

#!c++
static int32 aatkitUserEarnedIncentive(void *systemData, void *userData)

Note that 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.

Please note that due to limitations of the ad network SDKs, it’s not possible to handle the same ad network on multiple placements. Hence, AddApptr is limiting the usage of rewarded videos to a single placement.

In addition to classic banner and fullscreen ads, AATKit can be used to display special "promo" ads- they can be used, for example, to advertise your other applications. Promo is displayed in the form of fullscreen ad that would appear automatically no more than once per hour. The integration is extremely simple, just call:

#!c++
    s3eAATKitEnablePromo();

to enable automatic display of promotional ads. If you want to stop displaying promotional ads, just call:

#!c++
    s3eAATKitDisablePromo();

If you don't want to use automatic promo call:

#!c++
    s3eAATKitPreparePromo();

and then:

#!c++
    s3eAATKitShowPromo();

to manually show promo screen.

AATKit events

#!c++
#include "s3eAATKit.h"

static int32 aatkitHaveAd(void *systemData, void *userData) 
{
    if(systemData)
    {
        s3eAATKitAdInfo *info = (s3eAATKitAdInfo*)systemData;
        std::string msg("aatkitHaveAd callback: ");
        msg.append(info->placementName);
        s3eDebugOutputString(msg.c_str());
    }

    return 0;
}

static int32 aatkitHaveMultisizeAd(void *systemData, void *userData)
{
    if(systemData)
    {
        s3eAATKitAdInfo *info = (s3eAATKitAdInfo*)systemData;
        std::string msg("aatkitHaveMultisizeAd callback: ");
        msg.append(info->placementName);
        s3eDebugOutputString(msg.c_str());
    }

    return 0;
}

static int32 aatkitNoAd(void *systemData, void *userData) 
{
    if(systemData)
    {
        s3eAATKitAdInfo *info = (s3eAATKitAdInfo*)systemData;
        std::string msg("aatkitNoAd callback: ");
        msg.append(info->placementName);
        s3eDebugOutputString(msg.c_str());
    }

    return 0;
}

static int32 aatkitPauseForAd(void *systemData, void *userData) 
{
    if(systemData)
    {
        s3eAATKitAdInfo *info = (s3eAATKitAdInfo*)systemData;
        std::string msg("aatkitPauseForAd callback: ");
        msg.append(info->placementName);
        s3eDebugOutputString(msg.c_str());
    }

    return 0;
}

static int32 aatkitResumeAfterAd(void *systemData, void *userData) 
{
    if(systemData)
    {
        s3eAATKitAdInfo *info = (s3eAATKitAdInfo*)systemData;
        std::string msg("aatkitResumeAfterAd callback: ");
        msg.append(info->placementName);
        s3eDebugOutputString(msg.c_str());
    }

    return 0;
}

static int32 aatkitShowingEmpty(void *systemData, void *userData) 
{
    if(systemData)
    {
        s3eAATKitAdInfo *info = (s3eAATKitAdInfo*)systemData;
        std::string msg("aatkitShowingEmpty callback: ");
        msg.append(info->placementName);
        s3eDebugOutputString(msg.c_str());
    }

    return 0;
}

static int32 aatkitUserEarnedIncentive(void *systemData, void *userData) 
{
    if(systemData)
    {
        s3eAATKitAdInfo *info = (s3eAATKitAdInfo*)systemData;
        std::string msg("aatkitUserEarnedIncentive callback: ");
        msg.append(info->placementName);
        s3eDebugOutputString(msg.c_str());
    }

    return 0;
}

static int32 aatkitObtainedAdRules(void *systemData, void *userData) 
{
    if(systemData)
    {
        s3eAATKitAdInfo *info = (s3eAATKitAdInfo*)systemData;
        std::string msg("aatkitObtainedAdRules callback: ");
        msg.append(info->fromTheServer ? "true" : "false");
        s3eDebugOutputString(msg.c_str());
    }

    return 0;
}

void Init()
{
    ...

    // Register AATKit Callbacks
    s3eAATKitRegister(S3E_AATKIT_CALLBACK_HAVE_AD, &aatkitHaveAd, NULL);
    s3eAATKitRegister(S3E_AATKIT_CALLBACK_HAVE_MULTISIZE_AD, &aatkitHaveMultisizeAd, NULL);
    s3eAATKitRegister(S3E_AATKIT_CALLBACK_NO_AD, &aatkitNoAd, NULL);
    s3eAATKitRegister(S3E_AATKIT_CALLBACK_PAUSE_FOR_AD, &aatkitPauseForAd, NULL);
    s3eAATKitRegister(S3E_AATKIT_CALLBACK_RESUME_AFTER_AD, &aatkitResumeAfterAd, NULL);
    s3eAATKitRegister(S3E_AATKIT_CALLBACK_SHOWING_EMPTY, &aatkitShowingEmpty, NULL);
    s3eAATKitRegister(S3E_AATKIT_CALLBACK_USER_EARNED_INCENTIVE, &aatkitUserEarnedIncentive, NULL);
    s3eAATKitRegister(S3E_AATKIT_CALLBACK_OBTAINED_AD_RULES, &aatkitObtainedAdRules, NULL);
}

Methods

void s3eAATKitInitWithConfiguration(const char* alternativeBundleID, const char* initialRules, bool shouldCacheRules, bool shouldReportMetricsUsingAlternativeBundleID, int testModeAccountID, bool consentRequired, int simpleConsent, bool consentAutomatic, const char* consentString)

void s3eAATKitInitialize() - Deprecated

void s3eAATKitInitWithTestMode(int testID) - Deprecated

void s3eAATKitEnablePromo() - Deprecated

Will be removed in a future release: Use PreparePromo and ShowPromo: instead.

void s3eAATKitDisablePromo() - Deprecated