> For the complete documentation index, see [llms.txt](https://docs.ayetstudios.com/v/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ayetstudios.com/v/product-docs/offerwall/sdk-integrations-deprecated/android-sdk.md).

# 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.

{% hint style="info" %}

### Updates History

**2024-08-16: v3.6** - Removed documentation for deprecated "Native Offer Feed" functionality. Recommended replacement is client or server side "Offerwall API".

**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)
{% endhint %}

## Eligible Placement & AdSlot Combinations <a href="#eligible-placement-and-adslot-combinations" id="eligible-placement-and-adslot-combinations"></a>

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 |
| -------------- | ----------- | ------------------------- |
| Android App    | Offerwall   | Android SDK               |

{% hint style="danger" %}
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.
{% endhint %}

## Getting Started&#x20;

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

* [x] Created an Account
* [x] Added a placement
* [x] Added an AdSlot

You will find more details here:

{% content-ref url="/pages/W7CE6bNya8L7RoaXXY21" %}
[Dashboard Setup](/v/product-docs/dashboard-setup.md)
{% endcontent-ref %}

{% hint style="info" %}
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.
{% endhint %}

## 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.

{% hint style="info" %}
We don't recommend a managed user balance!

Managed user balances don't work well alongside additional rewarded ad integrations.
{% endhint %}

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

{% hint style="info" %}
This form of user balance is recommended.

You will find additional information about callbacks at the end of the Adndroid SDK documentation.
{% endhint %}

## Download the Library

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

{% embed url="<https://www.ayetstudios.com/ayetpublisher3.6.jar>" %}

## Add the library to your Android Studio project <a href="#add-the-library-to-your-android-studio-project" id="add-the-library-to-your-android-studio-project"></a>

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":

<figure><img src="https://4086115684-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQYkbOrUvRXzrXgEDF9qs%2Fuploads%2Fs50nkfeXABoYuLkUHpdA%2F29.jpg?alt=media&amp;token=fd8d08a8-d562-4756-aa7e-fe7b38b298be" alt=""><figcaption></figcaption></figure>

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

```xml
<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:

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

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

```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 <a href="#initialize-the-sdk-and-managed-user-balances" id="initialize-the-sdk-and-managed-user-balances"></a>

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.&#x20;

{% hint style="info" %}
**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.
{% endhint %}

```php
@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:

```javascript
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:

```javascript
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:

```javascript
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.

## Proguard Rules / Release Builds <a href="#proguard-rules-release-builds" id="proguard-rules-release-builds"></a>

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 { *; }
```

{% hint style="info" %}
It's always highly recommended to test your release builds before publishing them on Google Play to verify that they behave as intended!
{% endhint %}

## Conversion Callbacks & Currency Handling <a href="#conversion-callbacks-and-currency-handling" id="conversion-callbacks-and-currency-handling"></a>

Learn about:

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

Click on the link below:

{% content-ref url="/pages/5sxVWIW1fto5Mmv1JxeJ" %}
[Callbacks & Testing](/v/product-docs/callbacks-and-testing.md)
{% endcontent-ref %}