Android SDK

The Android SDK allows you to easily monetize your app and reward your users with in-app currency. Your users get access to our offerwalls, allowing them to earn currency for completing offers.

Updates History

2022-04-12: v3.6 - Updated SDK to Android Api 30 (Android 11) and restored compliance with updated privacy requirements

2022-02-11: v3.5.2 - Removed Rewarded Video from documentation

2020-08-11: v3.5.1 - Updated documentation to introduce new parameters to differentiate chargebacks from conversions

2020-07-29: v3.5 - Improved UI / handling, removed deprecated INSTALL_REFERRER, performance improvements and bug fixes

2019-08-20: v3.4 - Updated Android SDK to support decimal places in payouts (currency amount) for native offers

2019-07-19: v3.3 - Updated Android SDK and documentation to reflect the adslot changes 2019-06-21: v3.2 - Native Offer Feed functionality

2019-02-01: v3.1 - Fixed conversion tracking issues under certain conditions (application lifecycle monitoring improved)

2018-11-29: v3.0 - Full support for API 26+ build targets, bugfixes, simplified use & improved handling under poor network conditions

2018-07-02: v2.1 - Fixed video ad orientation & resolution issues on Android 8.1

2018-06-18: v2.0 - Video Ads & Rewarded Video Ads 2017-11-01: v1.1 - Fixed incompatibilities with present GSON dependencies 2017-10-29: v1.0 - Initial Release of our Publisher SDK (Android)

Eligible Placement & AdSlot Combinations

The table below shows all Placement & AdSlot Type combinations that allow you to utilize the Android SDK integration.

Placement Type

AdSlot Type

Eligible Integration Type

If you integrate the Android SDK while using a different Placement & AdSlot combination in the ayeT-Studios dashboard, you won't be able to initialize the Offerwall or Native Offer Feed.

Getting Started

Before you start with the integration, make sure you have:

Created an Account
Added a placement
Added an AdSlot

You will find more details here:

🖥️pageDashboard Setup

Make sure to use the correct package name that you intend to use for your final app.

Or create a test placement with a different package name that matches the package name of your test app.

If package name of your placement and your actual app don't match, you can't initialize the Offerwall.

User Balance

The integration is simple and allows both managed and unmanaged user balances / currencies.

A managed user balance / currency is a user balance that is stored on our servers. We store user information and the amount of virtual currency a user owns. You can use balance listeners to manage the amount of currency each user has on our servers.

We don't recommend a managed user balance!

Managed user balances don't work well alongside additional rewarded ad integrations.

An unmanaged user balance / currency is a user balance that is stored on your servers. You receive callbacks and handle user wallets yourself.

This form of user balance is recommended.

You will find additional information about callbacks at the end of the Adndroid SDK documentation.

Download the Library

You can download the lastest version of our publisher library here:

Add the library to your Android Studio project

Copy the downloaded jar library to your Android Studio project (in the app/libs/ folder). Go to "Module Settings" (F12 or right-click your app in the Project View) and check the dependencies tab to make sure the library is added as a file dependency and set to "Compile":

Afterwards open your AndroidManifest.xml and add our offerwall activity to your application scope:

<activity
    android:name="com.ayetstudios.publishersdk.OfferwallActivity"
    android:configChanges="orientation|screenSize">
    <intent-filter android:label="offer">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="offer" android:host="com.example.myapplication" /> <!-- Replace with your lower case package name -->
    </intent-filter>
</activity>
<activity android:name="com.ayetstudios.publishersdk.VideoActivity" android:configChanges="orientation|screenSize" />

Another AndroidManifest.xml requirement is your AYET_APP_KEY which you can fetch from our publisher dashboard in your placement or adslot details - add it to the application scope as well:

<meta-data android:name="AYET_APP_KEY" android:value="xxxxxxxxxxxxxxxx" />

Also make sure to check your permissions in the AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" /> <!-- mandatory permission -->
<uses-permölmission android:name="android.permission.READ_PHONE_STATE" /> <!-- optional -->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /> <!-- optional -->
This is an example for a complete AndroidManifest.xml:
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.example.myapplication"> <!-- Replace with your lower case package name -->
<uses-permission android:name="android.permission.INTERNET" /> <!-- mandatory permission -->
<uses-permission android:name="android.permission.READ_PHONE_STATE" /> <!-- optional -->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /> <!-- optional -->
android:allowBackup="true"
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:supportsRtl="true"
android:theme="@style/AppTheme">
android:name=".MainActivity"
android:label="@string/app_name">
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
<!-- Publisher SDK Specific-->
android:name="com.ayetstudios.publishersdk.OfferwallActivity"
android:configChanges="orientation|screenSize">
<intent-filter android:label="offer">
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<data android:scheme="offer" android:host="com.example.myapplication" /> <!-- Replace with your lower case package name -->
<activity android:name="com.ayetstudios.publishersdk.VideoActivity" android:configChanges="orientation|screenSize"></activity>
<meta-data android:name="AYET_APP_KEY" android:value="xxxxxxxxxxxxxxxx" />
<!-- End of: Publisher SDK Specific-->

Initialize the SDK & Managed User Balances

In this step, we are going to initialize the SDK in the main activity. We also use callbacks to track the user's account balance - this is optional and not required if you're planning to manage user balances on your own servers.

Attention: The username or external identifier passed in the init call (e.g. username, hashed email address, etc.) will be accessible in the conversion callbacks through the {external_identifier} parameter.

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    AyetSdk.init(getApplication(), "username (external identifier)", new UserBalanceCallback() { // UserBalanceCallback is optional if you want to manage balances on your servers
            @Override
            public void userBalanceChanged(SdkUserBalance sdkUserBalance) {
                Log.d("AyetSdk" , "userBalanceChanged - available balance: "+sdkUserBalance.getAvailableBalance()); // this is the new total available balance for the user
            }

            @Override
            public void userBalanceInitialized(SdkUserBalance sdkUserBalance) {
                Log.d("AyetSdk" , "SDK initialization successful");
                Log.d("AyetSdk" , "userBalanceInitialized - available balance: "+sdkUserBalance.getAvailableBalance()); // this is the total available balance for the user
                Log.d("AyetSdk" , "userBalanceInitialized - spent balance: "+sdkUserBalance.getSpentBalance()); // this is the total amount spent with "AyetSdk.deductUserBalance(..)"
                Log.d("AyetSdk" , "userBalanceInitialized - pending balance: "+sdkUserBalance.getPendingBalance()); // this is the amount currently pending for conversion (e.g. user still has offer requirements to meet)
            }

            @Override
            public void initializationFailed() {
                Log.d("AyetSdk", "initializationFailed - please check APP API KEY & internet connectivity");
            }
        });

    setContentView(R.layout.activity_main);
}

If you want to make sure the SDK has been initialized and is ready to display the Offerwall or video ads, you can use the following function:

if (AyetSdk.isInitialized()) {
    Log.d("AyetSdk" , "SDK is ready");
} else {
    Log.d("AyetSdk" , "SDK is NOT ready");
}

If you want to spend user currency, for example if the user clicks a "purchaseInAppItem" button, you can utilize the deductUserBalance function:

mPurchaseInAppItemButton.setOnClickListener(new OnClickListener() {
    @Override
    public void onClick(View view) {
        int amount=100;
        AyetSdk.deductUserBalance(getApplication(), amount, new DeductUserBalanceCallback() {
            @Override
            public void success() {
                Log.d("AyetSdk" , "deductUserBalance - successful, new available balance: "+AyetSdk.getAvailableBalance());
                // TODO: activate the purchased content
            }

            @Override
            public void failed() {
                Log.d("AyetSdk" , "deductUserBalance - failed");
                // this usually means that the user does not have sufficient balance in his account
            }
        });
    }
});

Show the Offerwall

Showing the offerwall for an offerwall adslot is straight-forward, you can simply call showOfferwall from any Activity:

AyetSdk.showOfferwall(getApplication(), "offerwall adslot name");

showOfferwall starts the offerwall activity for the adslot you pass as second parameter and displays available tasks for the user to complete.

Request Native Offer Feed

If you want to display the offers manually in a custom form (e.g. "native offers"), you can call getNativeOffers for a Native Offer Feed adslot you created in your placement:

AyetSdk.getNativeOffers(getApplication(), "native adslot name", new NativeOffersCallback() {
                    @Override
                    public void onResult(boolean success, NativeOfferList responseMessage) {
                        if (success) {
                            Log.e("JSON Native Offers",  new Gson().toJson( responseMessage.offers ) );
                            MyApplication.this.nativeOfferCache=responseMessage.offers;
                        }
                    }
                });

getNativeOffers fetches all offers fitting this user / device in the background and calls NativeOffersCallback on completion. This usually takes between 0.5s and 4s depending on your adslot configuration and traffic sources.

After retrieving a list of native offers, you can store them and later activate one of the offers like this:

AyetSdk.activateOffer(MainActivity.this, MyApplication.nativeOfferCache.get(0).getId(), new ActivateOfferCallback() {
                        @Override
                        public void onFailed() {
                            // This is triggered if the offer is not available anymore or if connectivity problems are present
                        }

                        @Override
                        public void onSuccess() {
                            // This is triggered right before starting a Google Play intent or trying to open the default browser
                        }
                    });

activateOffer takes an offer id found in the native offer feed, checks the requirements and tries to reserve it for the user.

Class members for each AyetOffer entry are:

String id; // the id of the offer, used in activateOffer call
String name; // display name of the offer
String icon; // url to the offer icon
int category; // NativeOfferList.CATEGORY_INCENT | NativeOfferList.CATEGORY_NONINCENT
int type; // NativeOfferList.TYPE_CPI | NativeOfferList.TYPE_CPA | NativeOfferList.TYPE_CPL
String description; // a short description of the offer
String instructions; // conversion instructions for the user
int conversionTime; // average / estimated conversion time in seconds
int payout; // the payout in the configured virtual currency
ArrayList<AyetCreative> creatives; // optional: additional creative data (images, videos) for the offer	 y

Proguard Rules / Release Builds

If you're going to use Proguard in your release build to obfuscate your application, make sure to add the following rules to your proguard-rules.pro files:

-keep class com.ayetstudios.publishersdk.messages.** {*;}
-keep public class com.ayetstudios.publishersdk.AyetSdk
-keepclassmembers class com.ayetstudios.publishersdk.AyetSdk {
   public *;
}
-keep public interface com.ayetstudios.publishersdk.interfaces.UserBalanceCallback { *; }
-keep public interface com.ayetstudios.publishersdk.interfaces.DeductUserBalanceCallback { *; }

-keep class com.ayetstudios.publishersdk.models.VastTagReqData { *; }

It's always highly recommended to test your release builds before publishing them on Google Play to verify that they behave as intended!

Conversion Callbacks & Currency Handling

Learn about:

Setting up callbacks
IP Whitelists
Securing callbacks using HMAC Security Hash
Testing callbacks

Click on the link below:

💡pageCallbacks & Testing

PreviousSDK Integrations NextiOS SDK

Last updated 11 months ago