Offerwall SDK Integration: From Setup to First Revenue in 10 Minutes

By the Perkox Team · Updated August 2026

Most mobile apps and games monetize only the 3–5% of users who make in-app purchases. The other 95%—the vast majority of your audience—generate nothing. An offerwall flips that equation by letting those non-paying users earn your premium currency by completing sponsored offers instead. The result: higher ARPDAU, better retention, and a revenue stream that scales with your user base rather than your IAP conversion rate.

This offerwall SDK guide walks through a complete offerwall SDK integration from zero to live revenue. Whether you ship on Android, iOS, or React Native, you’ll have a working, fraud-resistant offerwall in your app by the end. We’ll cover registration, app configuration, SDK installation, postback setup, UI entry points, testing, and the most common mistakes developers make along the way.

New to the concept entirely? Start with our primer: What Is an Offerwall?

Table of Contents

1. What Is an Offerwall SDK?
2. Prerequisites
3. Step 1: Register at pub.perkox.com
4. Step 2: Add Your App and Configure Currency
5. Step 3: Install the SDK (Android / iOS / React Native)
6. Step 4: Configure the Postback URL
7. Step 5: Add the Offerwall Entry Point
8. Step 6: Test and Go Live
9. Common Integration Mistakes
10. FAQ

1. What Is an Offerwall SDK?

An offerwall SDK is a lightweight library you embed inside your mobile app or game that renders a rewarded-ad marketplace. When a user opens the offerwall, they see a list of sponsored tasks—installing another app, completing a survey, reaching level 10 in a game, signing up for a trial. Each task carries a reward denominated in your app’s virtual currency (coins, gems, tickets, whatever you define). When the user completes the task, the advertiser pays Perkox, Perkox pays you, and your user gets their currency. Everyone wins.

The SDK handles the hard parts for you:

• Offer fetching and rendering — a real-time, geo-targeted catalog of 1,200+ live CPI, CPA, and CPE offers, filtered to match each user’s device, country, and demographics.
• Reward attribution — tracking which user completed which offer, with signed transaction IDs that survive app restarts, network drops, and delayed conversions.
• Fraud prevention — device fingerprinting, emulator detection, and server-side validation that stops users from spoofing completions or double-claiming rewards.
• Analytics — impressions, click-through rates, completion rates, and revenue dashboards accessible from the Perkox publisher console.

Perkox ships native SDKs for Android (Kotlin/Java), iOS (Swift), React Native (JS/TS), Flutter (Dart), Unity (C#), and Web. All of them talk to the same backend, so you can mix and match platforms under one publisher account.

If you want the deeper theoretical background before touching code, read our full offerwall explainer.

2. Prerequisites

Before you begin offerwall setup, make sure you have the following ready. None of these are Perkox-specific—they’re standard mobile dev requirements:

• A live or near-live mobile app on Android (min SDK 21 / Android 5.0) or iOS (min iOS 13), or a React Native / Flutter / Unity project targeting those platforms.
• A developer machine with the platform toolchain installed: Android Studio + Gradle for Android, Xcode for iOS, Node.js 18+ for React Native.
• A virtual currency defined in your app — coins, gems, tickets, or any unit you can programmatically grant to a user. If you don’t have one yet, now is the time to add it.
• A backend server (strongly recommended) capable of receiving HTTP GET or POST requests. This is where the postback lands. If you don’t have a backend yet, you can use a serverless function (AWS Lambda, Cloudflare Workers, Vercel) for the same purpose.
• A Perkox publisher account — free to create, no approval wait for SDK access. We’ll set this up in Step 1.
• Basic familiarity with your build system — Gradle dependencies, CocoaPods, or npm/yarn. You don’t need to be an expert; we give you the exact snippets.

That’s it. No ad network mediation layer, no AdMob account, no minimum user count. Perkox works standalone.

3. Step 1: Register at pub.perkox.com

Your offerwall SDK integration starts at the Perkox publisher console. Registration is free and takes about 60 seconds.

1. Go to pub.perkox.com and click Sign Up.
2. Enter your work email, choose a password, and verify via the confirmation link sent to your inbox.
3. Complete your developer profile: company or solo dev, primary platform, and a contact method. This is used for payout coordination, not marketing.
4. Once inside the dashboard, you’ll see the Apps tab. This is where every integration begins.

You do not need to wait for manual approval to start integrating. You can create apps, grab API keys, and test the SDK in a sandbox environment immediately. Live revenue requires a quick compliance review (usually under 24 hours) once you’re ready to go live, which we cover in Step 6.

4. Step 2: Add Your App and Configure Currency

From the publisher console, click Add App and fill in the following:

• App name — your app’s display name.
• Platform — Android, iOS, or both (you can add the second platform later under the same app entry).
• Package name / Bundle ID — e.g. com.yourstudio.yourgame. Must match exactly what’s in your build; Perkox uses this to validate offer completions against the real install.
• App store URL — optional during setup, required before going live.
• Currency name — the display name users see (e.g. “Coins”, “Gems”).
• Currency exchange rate — how much real-world payout each unit of currency is worth to you. For example, if 1,000 coins = $1.00 of revenue for you, set the rate so the SDK can display accurate reward values to users.
• Rounding rules — whether fractional rewards round up, down, or to nearest. Most games round down to avoid over-crediting.

After saving, Perkox generates an App ID and an API Key for this app. You’ll need both in Step 3. Keep the API Key private — it identifies your app to the Perkox backend and should never be committed to a public repo.

Why currency configuration matters: The exchange rate determines how many coins a user earns per offer, which directly affects engagement. Set it too low and offers look unappealing; too high and you erode your margin. A good starting point is matching the value users would pay for the same currency via IAP, then adjusting based on completion-rate data from your analytics dashboard.

5. Step 3: Install the SDK

This is the core of how to integrate offerwall functionality into your codebase. Below are real, copy-paste-ready snippets for Android, iOS, and React Native. For Flutter, Unity, and Web, see the Perkox docs.

Android (Kotlin, Gradle)

Add the Perkox Maven repository and dependency to your root build.gradle.kts or settings.gradle.kts:

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven("https://maven.perkox.com")
    }
}

Then in your app-level build.gradle.kts:

dependencies {
    implementation("com.perkox:offerwall-sdk:2.4.1")
}

Initialize the SDK in your Application class:

import com.perkox.offerwall.PerkoxSDK
import com.perkox.offerwall.PerkoxConfig

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        val config = PerkoxConfig.Builder()
            .appId("YOUR_APP_ID")
            .apiKey("YOUR_API_KEY")
            .userId(getOrCreateUserId())
            .build()
        PerkoxSDK.initialize(this, config)
    }
}

For the full Android walkthrough including ProGuard rules, manifest permissions, and mediation coexistence, see our Android SDK complete guide.

iOS (Swift, CocoaPods)

Add the Perkox pod to your Podfile:

pod 'PerkoxOfferwall', '~> 2.4.1'

Run pod install, then initialize in your AppDelegate:

import PerkoxOfferwall

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        let config = PerkoxConfig(
            appId: "YOUR_APP_ID",
            apiKey: "YOUR_API_KEY",
            userId: getOrCreateUserId()
        )
        PerkoxSDK.initialize(config)
        return true
    }
}

Make sure your Info.plist includes the NSUserTrackingUsageDescription key if you target iOS 14.5+ and wish to participate in personalized offers. Non-personalized offers still work without ATT authorization.

React Native (JavaScript / TypeScript)

Install the package via npm or yarn:

npm install @perkox/offerwall-react-native
# or
yarn add @perkox/offerwall-react-native

For iOS, run cd ios && pod install after adding the package. Then initialize at the top of your app entry point:

import { PerkoxSDK } from '@perkox/offerwall-react-native';

useEffect(() => {
  PerkoxSDK.initialize({
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_API_KEY',
    userId: getOrCreateUserId(),
  });
}, []);

All three platforms expose the same conceptual API: initialize, showOfferwall, and a reward-callback listener. The internal implementation differs, but your integration logic stays consistent across platforms.

6. Step 4: Configure the Postback URL

This is the step that separates a toy integration from a production-grade one. The postback URL is an HTTP endpoint on your backend that Perkox calls every time a user completes an offer. Your server receives the completion details, validates them, and grants the reward to the user. Because the reward is granted server-side, a malicious user cannot simply fake a “completed” message in the client to get free currency.

In the Perkox publisher console, under your app’s Postback settings, enter a URL like:

https://api.yourstudio.com/v1/perkox/postback

Perkox will call this URL with query parameters (or POST body, your choice) including:

• user_id — the user ID you passed during SDK initialization.
• offer_name — human-readable offer title.
• reward_amount — reward in your app’s currency units.
• transaction_id — a unique, signed ID for idempotency.
• signature — HMAC of the request, using your API key, so you can verify authenticity.
• status — completed or reversed (for chargebacks or fraud reversals).

A minimal server-side handler (Node.js / Express) looks like this:

import crypto from 'crypto';
import express from 'express';

const app = express();
const API_KEY = process.env.PERKOX_API_KEY;

app.get('/v1/perkox/postback', async (req, res) => {
  const { user_id, reward_amount, transaction_id, signature, status } = req.query;

  // 1. Verify the HMAC signature
  const expectedSig = crypto
    .createHmac('sha256', API_KEY)
    .update(`${user_id}|${transaction_id}|${reward_amount}|${status}`)
    .digest('hex');

  if (signature !== expectedSig) {
    return res.status(403).send('Invalid signature');
  }

  // 2. Idempotency check — don't credit the same transaction twice
  const existing = await db.transactions.findByPk(transaction_id);
  if (existing) {
    return res.status(200).send('OK — already processed');
  }

  // 3. Credit the user
  if (status === 'completed') {
    await db.users.incrementCurrency(user_id, Number(reward_amount));
    await db.transactions.create({ id: transaction_id, userId: user_id, amount: reward_amount });
  } else if (status === 'reversed') {
    await db.users.decrementCurrency(user_id, Number(reward_amount));
  }

  // 4. Respond 200 so Perkox knows the postback succeeded
  res.status(200).send('OK');
});

The two things every handler must do: verify the signature (step 1) and deduplicate by transaction ID (step 2). Skip either and you open yourself to reward fraud or double-crediting on retries. For the complete postback spec including retry behavior, status codes, and signature algorithms, read our Offerwall Postback Guide (Complete).

7. Step 5: Add the Offerwall Entry Point

The SDK is installed and your backend is ready to receive rewards. Now you need a button or banner in your app that opens the offerwall. Placement matters: put it where users already look for ways to earn currency.

Common high-performing placements:

• Shop / store screen — next to IAP bundles, labeled “Earn free coins”.
• Currency shortage modal — when a user tries to buy something but doesn’t have enough currency, offer the offerwall as an alternative to paying.
• Main menu — a persistent “Free Rewards” or “Offers” button.
• Settings or profile — lower-traffic but useful for power users.

Opening the offerwall is a single call on every platform:

Android

PerkoxSDK.showOfferwall(context)

iOS

PerkoxSDK.showOfferwall(from: viewController)

React Native

import { TouchableOpacity, Text } from 'react-native';
import { PerkoxSDK } from '@perkox/offerwall-react-native';

<TouchableOpacity onPress={() => PerkoxSDK.showOfferwall()}>
  <Text>Earn Free Coins</Text>
</TouchableOpacity>

You should also register a client-side reward listener so the UI can refresh the user’s balance immediately when they return from the offerwall, even before the postback lands. The postback is the source of truth, but the client listener gives users instant feedback:

// React Native example
PerkoxSDK.onRewardEarned((reward) => {
  console.log(`User earned ${reward.amount} ${reward.currency}`);
  refreshUserBalance();
});

On Android and iOS, equivalent listeners exist via PerkoxSDK.setRewardListener { ... } and a delegate protocol respectively. See the platform-specific docs for details.

8. Step 6: Test and Go Live

Before shipping, validate the full flow in Perkox’s sandbox mode. Sandbox mode serves test offers that convert instantly and without real ad spend, so you can confirm end-to-end behavior without affecting revenue.

1. Enable sandbox in the publisher console under App Settings, or pass testMode: true in your SDK config.
2. Open the offerwall in your app on a real device (not just a simulator—some offer tracking requires a real device ID).
3. Complete a test offer and watch your backend logs. You should see the postback arrive within seconds.
4. Verify signature validation, idempotency, and reward crediting in your database.
5. Trigger a duplicate postback by re-requesting the same transaction ID from the console, and confirm your server returns 200 without double-crediting.
6. Test a reversal by manually sending a reversed status postback and confirming currency is deducted.

Once everything works in sandbox, flip to live mode, submit your app for Perkox compliance review (typically under 24 hours), and you’re earning. Your first real revenue usually appears within hours of going live, depending on your user volume.

For production hardening—signature rotation, IP allowlisting, rate limiting, and monitoring—read our Offerwall SDK Security Best Practices.

9. Common Integration Mistakes

After reviewing hundreds of integrations, these are the issues we see most often. Avoid them and you’ll save yourself a support ticket:

• Trusting client-side reward callbacks without a postback. Client callbacks are for UX feedback only. Without server-side postback validation, any sufficiently motivated user can spoof a reward and print unlimited currency. Always grant the authoritative reward from your backend.
• Not deduplicating by transaction ID. Perkox retries postbacks if your server is slow or returns a non-200 status. If you don’t store and check transaction IDs, a single user completion can credit twice (or twenty times on a bad network day).
• Hardcoding the API key in a public repo. Use environment variables, Gradle properties, or Xcode build configs. Rotate immediately if a key leaks.
• Using an unstable user ID. If userId changes between sessions (e.g. you use a random ID regenerated on every launch), rewards won’t reach the right user. Use a stable account ID or device-stable identifier.
• Burying the offerwall entry point. If users can’t find the offerwall, they can’t earn, and you can’t earn. Put the entry point on the main screen or shop, not three taps deep in settings.
• Setting the currency exchange rate too high. If rewards are too generous relative to IAP, users stop paying and you cannibalize your highest-margin revenue. Calibrate based on data, not guesses.
• Skipping sandbox testing. Going straight to live mode means the first real user is also your first test user. Test the full flow in sandbox first, every time.
• Ignoring reversals. If you only handle completed and never handle reversed, fraudulent or chargebacked offers leave you with negative-margin users. Always implement the reversal path.
• Not handling postback latency. Some offers convert minutes or hours after the user completes them (e.g. “reach level 20”). Make sure your reward UI doesn’t promise instant currency for delayed-conversion offer types.

10. FAQ

What is an offerwall SDK?

An offerwall SDK is a software development kit that lets mobile app and game developers embed a rewarded-ad offer wall inside their product. Users complete sponsored offers—such as installing apps, taking surveys, or reaching in-game levels—and the developer earns revenue, which is distributed to users as in-app currency. Perkox provides native SDKs for Android, iOS, React Native, Flutter, Unity, and Web.

How long does offerwall SDK integration take?

With the Perkox SDK, a standard integration can be completed in under 10 minutes. The process involves registering at pub.perkox.com, adding your app and configuring currency, installing the SDK via Maven or CocoaPods, setting up the postback URL, and placing an offerwall entry point in your UI. Advanced security and analytics features may add additional configuration time.

Do I need a backend server to integrate an offerwall?

A backend server is strongly recommended but not strictly required for basic client-side reward delivery. For secure reward validation, Perkox uses server-side postbacks that notify your backend when a user completes an offer. Your server then grants the reward, preventing client-side tampering and fraud. Client-side callbacks can be used for testing or non-critical rewards.

Which platforms does the Perkox offerwall SDK support?

Perkox offers native SDKs for Android (Kotlin/Java), iOS (Swift/Objective-C), React Native (JavaScript/TypeScript), Flutter (Dart), Unity (C#), and a Web SDK. All SDKs connect to the same dashboard, analytics, and postback infrastructure at pub.perkox.com.

How does the postback URL work and why is it important?

The postback URL is an endpoint on your backend server that Perkox calls whenever a user completes an offer. It receives parameters like user ID, offer name, reward amount, and a signed transaction ID. Your server validates the request, idempotently credits the reward, and responds with a 200 OK. This server-side flow is what makes offerwall monetization fraud-resistant and trustworthy for production apps.

Next Steps

You now have everything you need to complete a production-grade offerwall SDK integration: registration, app and currency configuration, SDK installation across Android, iOS, and React Native, postback setup with signature verification and idempotency, UI entry-point placement, sandbox testing, and a checklist of mistakes to avoid.

The fastest way to put this into practice is to create your free publisher account and add your first app. You can be testing real offers in sandbox mode within minutes:

Get Started Free at pub.perkox.com

For the complete SDK reference, platform-specific deep dives, and advanced configuration options, the Perkox documentation is your source of truth.

Related reading:

• What Is an Offerwall?
• Offerwall Android SDK Complete Guide
• Offerwall Postback Guide (Complete)
• Offerwall SDK Security Best Practices

Ready to monetize the 95% of users who never make an IAP? Start earning with Perkox today.