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:

[email protected]

When contacting support, include:

• App ID

• SDK version

• Android version

• Device model

• Error logs if available

• Description of the issue