Perkox React Native SDK: Complete Offerwall Integration Guide (2026)

Published August 22, 2026 · Perkox Developer Documentation

The Perkox React Native SDK (@perkoxofficial/react-native-sdk) is the only platform that ships a true native offerwall SDK for React Native — not a WebView wrapper. With a single JavaScript package, you can monetize both Android and iOS apps using high-converting offerwall inventory, native UI, full TypeScript support, and secure server-to-server reward postbacks. This guide walks through everything you need to perform a complete react native offerwall integration in 2026: installation, initialization, showing the offerwall, handling reward events, validating rewards server-side, sandbox testing, Expo support, and best practices.

If you are new to the offerwall monetization model generally, start with our primer What Is an Offerwall? before diving into the SDK specifics below.

What the Perkox React Native SDK Does

The Perkox React Native SDK exposes a single JavaScript API — PerkoxSDK — that bridges to fully native Android and iOS offerwall implementations. One install gives your app:

• A native, full-screen offerwall UI rendered with platform components (not an embedded browser).
• Real-time reward events delivered straight to your JavaScript layer via PerkoxSDK.onReward().
• Offerwall lifecycle events such as close via PerkoxSDK.onClose().
• TypeScript typings out of the box, so every method and reward object is statically typed.
• A sandbox beta mode for testing the full reward flow without real payouts.
• Server-to-server postback configuration for secure, fraud-resistant reward validation.

In short, the package @perkoxofficial/react-native-sdk replaces the brittle pattern of embedding a mobile website inside your React Native app. Instead it gives your JS code first-class access to the same native offerwall surface that powers Perkox’s standalone Android SDK and iOS SDK.

Why Perkox Is the Only Platform with a Native RN Offerwall SDK

Every other offerwall platform that “supports React Native” really ships a WebView URL and asks you to open it in a react-native-webview component. That approach has real costs:

• Performance: WebView offerwalls spin up a browser engine, re-paint on every scroll, and eat memory. Native offerwalls render at 60fps with platform views.
• UX gap: Modal transitions, back-button handling, and status-bar styling never quite match the host app inside a WebView.
• Fragile bridging: Reward signals are pushed through window.postMessage or URL hash polling — easy to miss during a reload or navigation.
• No real typings: You end up writing ad-hoc TypeScript over string messages.

Perkox is the only platform that invested in a true native module. The PerkoxSDK object is a real React Native NativeModule with typed methods (init, showOfferwall, onReward, onClose, setUserId) and event subscriptions that go through the standard bridge — the same mechanism your app uses for everything else. That means predictable lifecycle, reliable event delivery, and zero browser overhead.

For a deeper look at why this matters from a security perspective, see Offerwall SDK Security Best Practices.

Prerequisites

Before installing the SDK, confirm your project meets these minimum requirements:

You also need an active Perkox publisher account with an App ID and SDK Key. Create an app in the Perkox publisher dashboard to obtain these credentials.

Installation

1. Install the npm package

Install @perkoxofficial/react-native-sdk with your preferred package manager:

# npm
npm install @perkoxofficial/react-native-sdk

# yarn
yarn add @perkoxofficial/react-native-sdk

# pnpm
pnpm add @perkoxofficial/react-native-sdk

2. iOS — install pods

After the npm install, link the native iOS module with CocoaPods:

cd ios && pod install && cd ..

Then rebuild from Xcode or with npx react-native run-ios. The SDK’s pod is published through CocoaPods trunk, so no extra Podfile repository is needed.

3. Android — add JitPack repository

The Android native layer is distributed via JitPack. Add the JitPack maven repository to your project-level build.gradle (or settings.gradle for the newer Gradle versions):

// android/build.gradle  (or settings.gradle dependencyResolutionManagement)
allprojects {
  repositories {
    google()
    mavenCentral()
    maven { url 'https://jitpack.io' }
  }
}

Ensure the INTERNET permission is present in android/app/src/main/AndroidManifest.xml:

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

Rebuild with npx react-native run-android. That’s the full setup — no manual activity registration or permissions dialog required.

Quick Start: TypeScript Initialization

Import the SDK and initialize it once at app startup — typically inside your root component’s useEffect or an app bootstrap module. The PerkoxSDK.init() call configures credentials, identifies the player, and optionally enables sandbox mode.

import { useEffect } from 'react';
import { PerkoxSDK } from '@perkoxofficial/react-native-sdk';

export default function App() {
  useEffect(() => {
    PerkoxSDK.init({
      appId: 'YOUR_APP_ID',
      sdkKey: 'YOUR_SDK_KEY',
      playerId: 'user_12345',
      beta: false, // set true for sandbox mode
    })
      .then(() => console.log('Perkox SDK initialized'))
      .catch((err) => console.error('Perkox init failed:', err));
  }, []);

  // ...rest of app
}

The init options object is fully typed:

• appId — your Perkox application ID (string, required).
• sdkKey — your SDK key from the publisher dashboard (string, required).
• playerId — a stable unique identifier for the current user (string, required).
• beta — when true, routes all traffic to the sandbox environment for testing (boolean, optional).

init() returns a Promise, so you can await it or chain handlers. Avoid calling showOfferwall() before init resolves.

Showing the Offerwall

Once initialized, launch the offerwall from any user action — a “Earn rewards” button, a store menu entry, or a rewarded-modal trigger. PerkoxSDK.showOfferwall() presents a native full-screen offerwall over your current activity / view controller.

import { PerkoxSDK } from '@perkoxofficial/react-native-sdk';

function openOfferwall() {
  PerkoxSDK.showOfferwall()
    .then(() => console.log('Offerwall presented'))
    .catch((err) => console.warn('Offerwall could not be shown:', err));
}

// <Button title="Earn Coins" onPress={openOfferwall} />

The offerwall handles its own navigation, offer detail screens, and completion tracking. You only need to listen for the two event streams — rewards and close — described next.

Reward Events with PerkoxSDK.onReward()

Reward events fire whenever a user completes an offer and a reward is generated. Subscribe with PerkoxSDK.onReward(), which returns an unsubscribe function you should call on unmount to prevent leaks.

import { useEffect } from 'react';
import { PerkoxSDK } from '@perkoxofficial/react-native-sdk';

function usePerkoxRewards(onReward: (r: { amount: number; txid: string; status: string }) => void) {
  useEffect(() => {
    const unsubscribe = PerkoxSDK.onReward((reward) => {
      console.log('Reward received:', reward);
      // reward.amount  - number, reward value in your virtual currency
      // reward.txid    - string, unique transaction id for dedup
      // reward.status  - string, e.g. "completed" | "pending"
      onReward(reward);
    });
    return () => unsubscribe();
  }, [onReward]);
}

The reward object fields:

Offerwall Close Events

Subscribe to PerkoxSDK.onClose() to know when the user dismissed the offerwall and returned to your app. This is the right moment to refresh a balance, re-enable buttons, or show a “You earned X” toast.

import { useEffect } from 'react';
import { PerkoxSDK } from '@perkoxofficial/react-native-sdk';

useEffect(() => {
  const unsubscribe = PerkoxSDK.onClose(() => {
    console.log('Offerwall closed by user');
    // refreshBalance();  // re-fetch the server-validated balance
  });
  return () => unsubscribe();
}, []);

Both onReward and onClose follow the same subscribe/unsubscribe pattern, so you can compose them in a single useEffect block.

Server-Side Reward Validation (S2S Postback)

Client-side reward callbacks are convenient but they are not a security boundary. A user can kill the app before onReward fires, replay network traffic, or tamper with the JS bundle. The only safe way to grant permanent currency is to have Perkox call your server directly with a signed postback, and have your server credit the user after verifying the request.

Configure the postback URL

In the Perkox publisher dashboard, set a postback URL on your app. Perkox will HTTP GET (or POST) this URL whenever a reward is finalized. The default parameter format is:

https://yourdomain.com/postback?offer_id={offer_id}&payout={payout}&status={status}&player_id={player_id}&reward_amount={reward_amount}

Placeholders substituted by Perkox:

• {offer_id} — the identifier of the completed offer.
• {payout} — the real-currency payout to you (USD).
• {status} — completed or pending.
• {player_id} — the playerId you set during init or via setUserId.
• {reward_amount} — the reward in your virtual currency.

Server-side handler (Node.js example)

import express from 'express';

const app = express();

app.get('/postback', async (req, res) => {
  const { offer_id, payout, status, player_id, reward_amount, signature } = req.query;

  // 1. Verify the request signature with your SDK secret (HMAC).
  //    Perkox signs postbacks so you can reject forged requests.

  // 2. Idempotency: check that `offer_id` has not already been credited.
  //    Store credited offer_ids in your database.

  // 3. Only credit when status === 'completed'.
  if (status !== 'completed') {
    return res.status(200).send('ignored-pending');
  }

  // 4. Credit the user.
  await creditUser(player_id, Number(reward_amount), offer_id);

  // 5. Always respond 200 quickly so Perkox does not retry.
  res.status(200).send('ok');
});

app.listen(3000);

For the complete postback spec — signature algorithm, retry policy, IP allowlisting, and idempotency patterns — read the Offerwall Postback Guide.

Updating the User ID

If a user logs in or you otherwise change identity mid-session, call PerkoxSDK.setUserId() to update the player ID without re-initializing the SDK. This keeps reward attribution tied to the correct user.

import { PerkoxSDK } from '@perkoxofficial/react-native-sdk';

async function onUserLogin(newUserId: string) {
  await PerkoxSDK.setUserId(newUserId);
  console.log('Player ID updated to', newUserId);
}

Call setUserId before the user interacts with the offerwall again, so subsequent rewards are attributed to the new ID. There is no need to call init again — credentials persist for the lifetime of the JS context.

Expo Support Considerations

The Perkox React Native SDK contains native Android and iOS modules, so it cannot run inside Expo Go (which ships a fixed prebuilt binary). It is fully compatible with Expo when you use a custom development build via expo-dev-client:

1. Install the SDK: npm install @perkoxofficial/react-native-sdk.
2. Add expo-dev-client to your project.
3. Run expo prebuild to generate the native ios and android directories.
4. Run cd ios && pod install (iOS) and add the JitPack repository as described in Installation (Android).
5. Build a custom dev client: npx expo run:ios / npx expo run:android.

For EAS Build production deployments, the same JitPack and pod setup is applied automatically through your prebuild config. If you rely on Expo Go for fast iteration, you can keep your non-SDK code in Expo Go and only switch to a custom client when testing offerwall flows.

Testing and Sandbox Mode

Before going live, test the full reward flow without spending real advertiser budget. Pass beta: true to PerkoxSDK.init() to route the SDK into the Perkox sandbox:

PerkoxSDK.init({
  appId: 'YOUR_APP_ID',
  sdkKey: 'YOUR_SDK_KEY',
  playerId: 'test_user_1',
  beta: true, // sandbox environment
});

In sandbox mode:

• The offerwall shows a curated set of test offers that complete quickly.
• Reward events fire through onReward() with sandbox txid values.
• S2S postbacks are delivered to your configured postback URL with a sandbox flag, so you can test your verification handler end-to-end.

Recommended test checklist:

1. Initialize with beta: true and confirm the init Promise resolves.
2. Open the offerwall and complete a test offer.
3. Verify onReward fires with status: "completed" and a non-zero amount.
4. Verify your server postback endpoint receives, validates, and credits the reward.
5. Close the offerwall and verify onClose fires.
6. Repeat the same offer and confirm your server dedupes by offer_id.

Once sandbox passes end-to-end, flip beta: false and ship. Remember to also review SDK security best practices before production launch.

FAQ

Get Started with Perkox

Package: @perkoxofficial/react-native-sdk · Keywords: perkox react native sdk, offerwall react native, react native offerwall integration, @perkoxofficial/react-native-sdk.