Perkox React Native SDK

Official documentation for integrating the Perkox Offerwall into React Native applications.

📖 Table of Contents

Getting Started├── Introduction├── Requirements├── Installation├── Quick Start
Integration├── SDK Initialization├── Configuration├── User Identification├── Show Offerwall├── Reward Events├── Offerwall Events├── Update User ID
Platform Setup├── Android Setup├── iOS Setup├── Expo Support├── Sandbox vs Production
Advanced├── API Reference├── SDK Configuration├── Error Handling├── Debugging├── Best Practices
Backend├── Server-to-Server Postbacks├── Reward Validation
Resources├── FAQ├── Troubleshooting├── Changelog

---

Page 1 — Introduction

# React Native SDK
Welcome to the Perkox React Native SDK.
The Perkox SDK enables mobile applications to integrate a native Offerwall experience with minimal code while supporting both Android and iOS through a single React Native package.
## Features
- Native Android & iOS implementation- React Native bridge- TypeScript support- Reward event callbacks- Offerwall lifecycle events- Secure SDK initialization- Sandbox & Production environments
## Supported Platforms
| Platform | Supported ||----------|-----------|| React Native | 0.72+ || Android | API 21+ || iOS | 13+ |
## Package
npm
@perkoxofficial/react-native-sdk

---

Page 2 — Installation

# Installation
Install using npm
```bashnpm install @perkoxofficial/react-native-sdk

or Yarn

yarn add @perkoxofficial/react-native-sdk

or PNPM

pnpm add @perkoxofficial/react-native-sdk

iOS

cd ios
pod install
cd ..

Android

Add JitPack repository

maven { url 'https://www.jitpack.io' }

Ensure

android.permission.INTERNET

exists in AndroidManifest.xml.

---
# Page 3 — Quick Start
```markdown# Quick Start
Import the SDK
```tsximport { PerkoxSDK } from "@perkoxofficial/react-native-sdk";

Initialize

PerkoxSDK.init({
 appId: "...",
 sdkKey: "...",
 playerId: "...",
 beta: false
});

Launch Offerwall

PerkoxSDK.showOfferwall();

---
# Page 4 — SDK Initialization
Explain:
- appId- sdkKey- playerId- beta
Include a parameter table.
| Parameter | Required | Description ||-----------|----------|-------------|| appId | ✅ | Perkox App ID || sdkKey | ✅ | SDK Authentication Key || playerId | Recommended | Unique User Identifier || beta | Optional | Enable Sandbox Mode |
---
# Page 5 — Offerwall
```tsxPerkoxSDK.showOfferwall();

Explain:

• Native fullscreen experience

• Authentication

• Reward flow

• Automatic dismissal

---

Page 6 — Reward Events

const unsubscribe = PerkoxSDK.onReward((reward)=>{
 console.log(reward)
});

Document the reward object:

{ amount:100, txid:"xxxx", status:"completed"}

Explain that rewards should always be validated via the server-to-server (S2S) postback before granting permanent in-app currency or items.

---

Page 7 — Offerwall Events

PerkoxSDK.onClose(()=>{
 console.log("Offerwall closed")
});

Lifecycle:

Init
↓
Show Offerwall
↓
User Completes Offer
↓
Reward Event
↓
Offerwall Closed

---

Page 8 — API Reference

Document every SDK method in one place.

Method	Description
init()	Initialize SDK
showOfferwall()	Display Offerwall
setUserId()	Update current user
onReward()	Listen for rewards
onClose()	Listen for Offerwall close

---

Page 9 — Android Configuration

• Minimum SDK

• Gradle requirements

• JitPack

• Internet permission

• Common Android issues

---

Page 10 — iOS Configuration

• CocoaPods

• Deployment target

• Privacy Manifest

• Framework integration

• Common Xcode issues

Given your recent App Store experience, this page should also include a section on Apple Privacy Manifest requirements and how to ensure the embedded framework contains a valid PrivacyInfo.xcprivacy.

---

Page 11 — Sandbox & Production

Explain:

beta = true

Uses Sandbox

beta = false

Uses Production

Include guidance on when to use each environment.

---

Page 12 — Best Practices

• Initialize the SDK once when the app starts.

• Use a stable, unique playerId.

• Verify rewards using S2S postbacks.

• Test thoroughly in Sandbox before switching to Production.

• Keep the SDK updated to the latest release.

---

Page 13 — Troubleshooting

Examples:

Offerwall doesn't open

• Check appId and sdkKey.

• Verify package name/bundle identifier matches the Perkox Dashboard.

No rewards

• Confirm S2S postback is configured.

• Ensure playerId is valid.

iOS build fails

• Run pod install.

• Verify the deployment target.

• Check the embedded privacy manifest.

---

Page 14 — FAQ

• Does the SDK support Expo?

• Can I change the user after login?

• How do I enable Sandbox?

• How do rewards work?

• Is internet access required?

---

Page 15 — Changelog

Maintain release notes such as:

v1.0.8
• Initial public release• Native Android & iOS bridge• Reward callbacks• TypeScript support
v1.0.9
• Apple Privacy Manifest improvements• Bug fixes• Stability enhancements

Final recommendation

Instead of publishing only a README, build a developer portal in GitBook with these sections. It will provide a much better onboarding experience for publishers and present Perkox as a mature developer platform. You can then extend the documentation later with separate guides for Android, iOS, Flutter, Unity, REST APIs, webhooks, and server-to-server integrations.