> 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-v2/android-sdk-v2.md).

# Android SDK (v2)

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

{% hint style="info" %}

### Updates History

**2025-12-02: v1.0.0** - Release the Android SDK v2
{% 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   |
| -------------- | ------------- |
| Android        | Offerwall     |
| Android        | Surveywall    |
| Android        | Offerwall API |

{% 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 SDK.
{% endhint %}

## Demo App&#x20;

{% embed url="<https://github.com/ayetstudios/android-sdk-v2-demo-app>" %}

## 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 can find more details here:

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

{% hint style="warning" %}
Make sure to use the correct package name that you intend to use for your final app. Alternatively, 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 SDK.
{% endhint %}

## Adding the SDK Dependency

To add the SDK to your project, simply update your `build.gradle.kts` file to add the following dependency:

```kts
dependencies {
    implementation("io.ayet:android-sdk-v2:1.0.3")
}
```

Once this has been added, sync your project to apply the changes:

<figure><img src="https://4086115684-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQYkbOrUvRXzrXgEDF9qs%2Fuploads%2FcMiTl7nsBsKw0MkeOgXy%2Fimage.png?alt=media&amp;token=576dafef-344b-47b0-a7c0-2397aefc4043" alt=""><figcaption></figcaption></figure>

## Add the internet permission to AndroidManifest <a href="#add-the-library-to-your-android-studio-project" id="add-the-library-to-your-android-studio-project"></a>

Add the following tag to your `AndroidManifest.xml` , just before the `application` tag:

```xml
<uses-permission android:name="android.permission.INTERNET" />
```

Example of completed `AndroidManifest.xml`:

```xml
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <uses-permission android:name="android.permission.INTERNET" />

    <application
        android:allowBackup="true"
        android:dataExtractionRules="@xml/data_extraction_rules"
        android:fullBackupContent="@xml/backup_rules"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/Theme.AyetSDKExample">
        <activity
            android:name=".MainActivity"
            android:exported="true"
            android:label="@string/app_name"
            android:theme="@style/Theme.AyetSDKExample">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>
```

## Import and initialize the SDK <a href="#initialize-the-sdk-and-managed-user-balances" id="initialize-the-sdk-and-managed-user-balances"></a>

In this step, we will import and initialize the SDK in the main activity.

{% hint style="info" %}
**Note:** The `externalIdentifier` passed in the init call is the user's identifier on your end. This will be accessible in the conversion callbacks through the `{external_identifier}` parameter. The `placementId` is the unique ID assigned to your placement when it's created through our dashboard.
{% endhint %}

First, import the library:

```kt
import com.ayet.sdk.AyetSdk                
```

Then, call the `AyetSdk.init` method:

```kt
class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()

        AyetSdk.init(this, YOUR_PLACEMENT_ID, "USER_EXTERNAL_IDENTIFIER")

        setContent {
            AyetSDKExampleTheme {
                Scaffold(modifier = Modifier.fillMaxSize()) { innerPadding ->
                    MainScreen(modifier = Modifier.padding(innerPadding))
                }
            }
        }
    }
}
```

## Show the Offerwall

To show the offerwall, simply call the `showOfferwall` method:

```kt
val context = LocalContext.current
AyetSdk.showOfferwall(context, "YOUR_OFFERWALL_ADSLOT_NAME")
```

{% hint style="info" %}
The `YOUR_OFFERWALL_ADSLOT_NAME` parameter can be found by clicking on the adslot on your dashboard. This is only available on **Offerwall** adslots.
{% 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 %}

## Additional Methods

## Fetch Offers

To fetch a list of all offers in JSON format, simply call the `getOffers` method:

```kt
AyetSdk.getOffers("YOUR_OFFERWALL_API_ADSLOT_NAME") { offersJson ->
    if (offersJson != null) {
        Log.d("MainActivity", "Offers received: $offersJson")
    } else {
        Log.w("MainActivity", "Failed to get offers - null response")
    }
}
```

{% hint style="info" %}
The `YOUR_OFFERWALL_API_ADSLOT_NAME` parameter can be found by clicking on the adslot on your dashboard. This is only available on **Offerwall API** adslots.
{% endhint %}

## Show Reward Status

The Reward Status page allows users to see their clicked and in-progress offers and allows users to request support / submit tickets. The reward status is also part of the offerwall and the surveywall. To show the reward status page stand-alone, simply call the `showRewardStatus` method:

```kt
val context = LocalContext.current
AyetSdk.showRewardStatus(context)
```

## Show the Surveywall

To show the surveywall, simply call the `showSurveywall` method:

```kt
val context = LocalContext.current
AyetSdk.showSurveywall(context, "YOUR_SURVEYWALL_ADSLOT_NAME")
```

{% hint style="info" %}
The `YOUR_SURVEYWALL_ADSLOT_NAME` parameter can be found by clicking on the adslot on your dashboard. This is only available on **Surveywall** adslots.
{% endhint %}

## Set custom parameters

Set custom parameters for callbacks. Set up to 5 custom parameters.

```kt
AyetSdk.setTrackingCustom1("custom1")
AyetSdk.setTrackingCustom2("custom2")
AyetSdk.setTrackingCustom3("custom3")
AyetSdk.setTrackingCustom4("custom4")
AyetSdk.setTrackingCustom5("custom5")
```

{% hint style="info" %}
Note: Custom parameters must also be added to your callback URL to receive them in your S2S callbacks.
{% endhint %}

More information here:

{% content-ref url="/pages/4uQiMxtgnAayAHR8ZeXt" %}
[Offerwall Callbacks](/v/product-docs/callbacks-and-testing/callbacks/offerwall-callbacks.md)
{% endcontent-ref %}

## Set Age and Gender

Additionally, you may optionally pass user age and gender to us. This can help us match users to the best and most appropriate offers for them.

```kt
AyetSdk.setGender(Gender.MALE)
AyetSdk.setGender(Gender.FEMALE)
AyetSdk.setAge(25)
```

## Notes

* When calling certain SDK methods, `context` must be passed. When passing `context` from `onCreate` for example, this will simply be `this`. If calling from elsewhere, the context will need to be provided from `LocalContext.current`.