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

# Perkox Offerwall SDK for Android

The **Perkox Offerwall SDK for Android** is a lightweight SDK that allows mobile app and game developers to integrate the Perkox Offerwall directly into their Android applications.

With Perkox, users can earn in-app rewards by completing offers, surveys, and other rewarded engagement activities.

The SDK is designed to provide a simple integration flow while giving publishers access to rewarded monetization, analytics, and secure server-side reward validation.

***

### Requirements

Before integrating the Perkox Android SDK, make sure your project meets the following requirements:

| Requirement       | Version                   |
| ----------------- | ------------------------- |
| Android minSdk    | 21 / Android 5.0 Lollipop |
| Android targetSdk | 33                        |
| Java              | 17                        |
| Kotlin            | 1.9.0+                    |
| AndroidX          | Required                  |

***

### Required Permission

The SDK requires internet access to load the offerwall and communicate with Perkox services.

This permission is automatically included through Android manifest merging:

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

***

## Installation

### Step 1: Download the AAR

Download the latest SDK file:

```
perkox-android-sdk-release.aar
```

The file should be downloaded from the official Perkox GitHub Releases page or provided by the Perkox team.

***

### Step 2: Add the AAR to Your Project

Copy the downloaded `.aar` file into your app module’s `libs` folder.

Your project structure should look like this:

```
your-app/
└── app/
    └── libs/
        └── perkox-android-sdk-release.aar
```

***

### Step 3: Add SDK Dependencies

Add the Perkox SDK AAR file and required AndroidX dependencies to your app-level Gradle file.

#### Groovy — `build.gradle`

```
dependencies {
    implementation files('libs/perkox-android-sdk-release.aar')

    // Required dependencies
    implementation 'androidx.appcompat:appcompat:1.6.1'
    implementation 'androidx.core:core-ktx:1.10.1'
}
```

#### Kotlin DSL — `build.gradle.kts`

```
dependencies {
    implementation(files("libs/perkox-android-sdk-release.aar"))

    // Required dependencies
    implementation("androidx.appcompat:appcompat:1.6.1")
    implementation("androidx.core:core-ktx:1.10.1")
}
```

***

## Quick Start

After installing the SDK, you can launch the Perkox Offerwall using your **App ID**, **SDK Key**, and a unique **Player ID**.

You can find your App ID and SDK Key inside the Perkox Publisher Dashboard.

***

### Kotlin Implementation

```
import com.perkoxofferwall.sdk.PerkoxOfferwall

private fun showOfferwall() {

    // Create and launch the offerwall
    val offerwall = PerkoxOfferwall.create(
        "YOUR_APP_ID",   // Your App ID
        "YOUR_SDK_KEY",  // Your SDK Key
        "Player_123"     // Unique player ID
    )

    offerwall.launch(this)
}
```

***

### Java Implementation

```
import com.perkoxofferwall.sdk.PerkoxOfferwall;
import com.perkoxofferwall.sdk.Offerwall;

private void showOfferwall() {
    Offerwall offerwall = PerkoxOfferwall.INSTANCE.create(
        "YOUR_APP_ID",   // Your App ID
        "YOUR_SDK_KEY",  // Your SDK Key
        "USER_123"       // Unique player ID
    );

    offerwall.launch(this);
}
```

***

## API Reference

### PerkoxOfferwall

`PerkoxOfferwall` is the main entry point for creating and launching the Perkox Offerwall.

| Method     | Parameters                                            | Returns     | Description                      |
| ---------- | ----------------------------------------------------- | ----------- | -------------------------------- |
| `create()` | `appId: String`, `sdkKey: String`, `playerId: String` | `Offerwall` | Creates a new Offerwall instance |

***

### Offerwall

The `Offerwall` object is used to launch the offerwall and listen to basic offerwall events.

| Method / Callback | Parameters                    | Description                                        |
| ----------------- | ----------------------------- | -------------------------------------------------- |
| `launch()`        | `activity: Activity`          | Launches the offerwall                             |
| `onReward`        | `(Map<String, Any?>) -> Unit` | Callback triggered when a reward event is received |
| `onClose`         | `() -> Unit`                  | Callback triggered when the offerwall is closed    |

***

## Listening to Events

You can listen to reward and close events by setting callbacks before launching the offerwall.

### Important Reward Handling Notice

Do **not** rely only on SDK reward callbacks to grant rewards to users.

SDK callbacks only work while the offerwall is active inside the app. For accurate and reliable reward processing, rewards should be handled server-side using the **Postback URL** configured in your Perkox dashboard.

Recommended reward flow:

```
User completes offer
→ Perkox validates conversion
→ Perkox sends postback to your server
→ Your backend verifies the event
→ Your backend credits the user
```

Use SDK callbacks mainly for UI feedback, logs, or temporary in-app updates.

The `onReward` callback may be triggered multiple times for the same transaction with different statuses, such as `pending`, `approved`, `rejected`, or `reversed`.

***

### Kotlin Event Example

```
val offerwall = PerkoxOfferwall.create(
    "YOUR_APP_ID",
    "YOUR_SDK_KEY",
    "Player_123"
)

offerwall.onReward = { reward ->
    val amount = reward["amount"]          // Double - reward amount
    val status = reward["status"]          // String - reward status
    val txid = reward["txid"]              // String - unique transaction ID
    val playerId = reward["player_id"]     // String - player ID

    Log.d("Perkox", "Reward received! Amount: $amount, Status: $status")
}

offerwall.onClose = {
    Log.d("Perkox", "Offerwall closed")
}

offerwall.launch(this)
```

***

### Java Event Example

```
Offerwall offerwall = PerkoxOfferwall.INSTANCE.create(
    "YOUR_APP_ID",
    "YOUR_SDK_KEY",
    "Player_123"
);

offerwall.setOnReward(reward -> {
    Double amount = (Double) reward.get("amount");
    String status = (String) reward.get("status");
    String txid = (String) reward.get("txid");
    String playerId = (String) reward.get("player_id");

    Log.d("Perkox", "Reward received! Amount: " + amount + ", Status: " + status);

    return null;
});

offerwall.setOnClose(() -> {
    Log.d("Perkox", "Offerwall closed");

    return null;
});

offerwall.launch(this);
```

***

## Reward Data Fields

When a reward event is received, the SDK may return the following fields:

| Field       | Type     | Description                                |
| ----------- | -------- | ------------------------------------------ |
| `amount`    | `Double` | Reward amount                              |
| `txid`      | `String` | Unique transaction ID                      |
| `status`    | `String` | Reward status                              |
| `player_id` | `String` | Player ID passed during SDK initialization |

***

### Reward Statuses

| Status     | Description                             | Recommended Action                              |
| ---------- | --------------------------------------- | ----------------------------------------------- |
| `pending`  | Reward is being reviewed or processed   | Do not grant final reward yet                   |
| `approved` | Reward has been validated               | Credit the user server-side                     |
| `rejected` | Reward was not approved                 | Do not credit the user                          |
| `reversed` | Previously approved reward was reversed | Adjust or remove the reward if already credited |

***

## Player ID

The `playerId` should be a unique and stable identifier for the user inside your app or game.

Examples:

```
player123
user_98765
account_45678
```

The Player ID is important because it allows your backend to identify which user should receive the reward.

Best practices:

* Use a stable internal user ID
* Do not use random temporary values
* Do not use sensitive personal information
* Make sure the same user keeps the same Player ID across sessions

***

## Reward Validation Best Practice

For production integrations, Perkox recommends using server-side reward validation through postbacks.

The SDK callback is useful for listening to events inside the app, but the final reward credit should happen on your backend.

Recommended production setup:

```
App launches Perkox Offerwall with playerId
→ User completes an offer
→ Perkox validates conversion
→ Perkox sends postback to publisher backend
→ Publisher backend checks txid and status
→ Publisher backend credits the user
```

This helps prevent duplicate rewards, missed rewards, and client-side manipulation.

***

## Troubleshooting

### 1. Offerwall Not Loading

Check the following:

* Verify that your `appId` is correct
* Verify that your `sdkKey` is correct
* Check the device internet connection
* Make sure the `playerId` is not empty
* Confirm that your app has internet permission
* Make sure the app/property is active inside the Perkox dashboard

***

### 2. AAR File Not Found

Check the following:

* Make sure the `.aar` file is inside the `app/libs` folder
* Verify that the file name matches your Gradle configuration
* Sync the Gradle project again
* Clean and rebuild the project

Example:

```
app/libs/perkox-android-sdk-release.aar
```

***

### 3. Class Not Found Errors

Make sure the required dependencies are included:

```
implementation 'androidx.appcompat:appcompat:1.6.1'
implementation 'androidx.core:core-ktx:1.10.1'
```

For Kotlin DSL:

```
implementation("androidx.appcompat:appcompat:1.6.1")
implementation("androidx.core:core-ktx:1.10.1")
```

Then sync and rebuild your project.

***

### 4. Reward Callback Not Triggering

Possible reasons:

* The offerwall was closed before the event was returned
* The conversion is still pending
* The reward was processed server-side through postback
* The user did not complete the offer requirements
* The transaction status has not changed yet

For production reward handling, always rely on server-side postbacks.

***

## Changelog

### v1.0.0

Initial Android SDK release.

Included:

* Lightweight AAR integration
* Perkox Offerwall launch support
* Android and Java usage examples
* Reward callback support
* Close callback support
* Server-side postback recommendation

***

## Support

For questions, issues, or feature requests, contact:

```
support@perkox.com
```

When contacting support, include:

* App ID
* SDK version
* Android version
* Device model
* Error logs if available
* Description of the issue