> 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-react-native-sdk.md).

# Perkox React Native SDK

## 📖 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.