> 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

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

Official React Native SDK for integrating the **Perkox Offerwall** into iOS and Android applications. Allow your users to earn rewards by completing offers, surveys, and engagement tasks with native performance.

***

#### Key Features

* **Single Cross-Platform Package**: Clean TypeScript/JavaScript API supporting both iOS and Android.
* **Native Performance**: Backed by the official native Android (Kotlin) and iOS (Swift/XCFramework) Perkox SDKs.
* **Architecture Support**: Compatible with React Native 0.60+ (both New Architecture and Paper legacy architecture).
* **Expo Prebuild & Dev Client**: Fully compatible with modern Expo workflows via Expo Config Plugins or Prebuild.
* **Apple Privacy Manifest**: Bundled with Apple's mandatory `PrivacyInfo.xcprivacy` out of the box.

***

#### Requirements

| Requirement               | Supported Version                                                         |
| ------------------------- | ------------------------------------------------------------------------- |
| **React Native**          | `0.60.0+` (New Architecture & Paper supported)                            |
| **Expo**                  | Bare React Native or Expo Dev Client / Prebuild (`expo-build-properties`) |
| **iOS Deployment Target** | `13.0+`                                                                   |
| **Android minSdk**        | `21` (Android 5.0 Lollipop) or higher                                     |
| **Android targetSdk**     | `36` (Android 15 ready)                                                   |

***

### Installation

Install the SDK using your package manager of choice:

```bash
# Using NPM
npm install @perkoxofficial/react-native-sdk

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

# Using PNPM
pnpm add @perkoxofficial/react-native-sdk
```

***

### Platform Setup

#### iOS Setup

After installing the package, install the required CocoaPods dependencies:

```bash
cd ios && pod install && cd ..
```

> **Apple Privacy Manifest**: The SDK includes Apple's mandatory `PrivacyInfo.xcprivacy` manifest automatically. No manual privacy configuration is required.

#### Android Setup

1. **Permissions**: The `INTERNET`, `ACCESS_NETWORK_STATE`, and `AD_ID` permissions are included automatically via Android Manifest merging:

   ```xml
   <uses-permission android:name="android.permission.INTERNET" />
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
   <uses-permission android:name="com.google.android.gms.permission.AD_ID" />
   ```
2. **JitPack Repository**: Ensure `maven { url 'https://www.jitpack.io' }` is present in your project's `android/build.gradle` (or `settings.gradle`):

   ```groovy
   allprojects {
       repositories {
           google()
           mavenCentral()
           maven { url 'https://www.jitpack.io' }
       }
   }
   ```

***

### Quick Start Guide

#### Basic Implementation

```tsx
import React, { useEffect } from 'react';
import { View, Button, Alert } from 'react-native';
import { PerkoxSDK, PerkoxReward } from '@perkoxofficial/react-native-sdk';

export default function App() {
  useEffect(() => {
    // 1. Initialize the Perkox SDK
    PerkoxSDK.init({
      appId: "YOUR_APP_ID",       // Your App ID from Perkox Dashboard
      sdkKey: "YOUR_SDK_KEY",     // Your SDK Key from Perkox Dashboard
      playerId: "Player_123",     // Unique player / user identifier
      beta: false,                // Set to true to test with sandbox backend
    });

    // 2. Listen to Reward events
    const unsubscribeReward = PerkoxSDK.onReward((reward: PerkoxReward) => {
      console.log('Reward received:', reward);
      Alert.alert('Reward', `Received ${reward.amount} coins!`);
    });

    // 3. Listen to Offerwall Close events
    const unsubscribeClose = PerkoxSDK.onClose(() => {
      console.log('Offerwall closed');
    });

    // Clean up listeners on unmount
    return () => {
      unsubscribeReward();
      unsubscribeClose();
    };
  }, []);

  const handleShowOfferwall = async () => {
    const success = await PerkoxSDK.showOfferwall();
    if (!success) {
      Alert.alert('Error', 'Failed to launch Perkox Offerwall.');
    }
  };

  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Button title="Open Offerwall" onPress={handleShowOfferwall} />
    </View>
  );
}
```

***

### API Reference

#### `PerkoxSDK` (Static Methods)

| Method                    | Parameters                       | Returns            | Description                                                                         |
| ------------------------- | -------------------------------- | ------------------ | ----------------------------------------------------------------------------------- |
| `init(config)`            | `PerkoxInitConfig`               | `Promise<boolean>` | Initializes the SDK with global configuration.                                      |
| `showOfferwall(options?)` | `PerkoxInitConfig?`              | `Promise<boolean>` | Launches the native Offerwall modal.                                                |
| `setUserId(userId)`       | `string`                         | `Promise<boolean>` | Updates the active player / user identifier dynamically.                            |
| `onReward(callback)`      | `(reward: PerkoxReward) => void` | `() => void`       | Registers a listener for reward events. Returns an unsubscribe function.            |
| `onClose(callback)`       | `() => void`                     | `() => void`       | Registers a listener for Offerwall dismiss events. Returns an unsubscribe function. |

***

#### Configuration Options (`PerkoxInitConfig`)

| Field      | Type      | Required | Description                                                                |
| ---------- | --------- | :------: | -------------------------------------------------------------------------- |
| `appId`    | `string`  |  **Yes** | Your unique App ID from the Perkox Publisher Dashboard.                    |
| `sdkKey`   | `string`  |  **Yes** | Your SDK Key from the Perkox Publisher Dashboard.                          |
| `playerId` | `string`  |  **Yes** | Unique identifier for the user (cannot be empty).                          |
| `beta`     | `boolean` |    No    | When `true`, routes to the beta sandbox environment (`beta.perkwall.com`). |

***

#### Reward Object (`PerkoxReward`)

| Field    | Type     | Description                                    |
| -------- | -------- | ---------------------------------------------- |
| `amount` | `number` | The reward amount / currency credited.         |
| `txid`   | `string` | Unique transaction ID for the reward.          |
| `status` | `string` | Reward transaction status (`completed`, etc.). |

***

### Critical Requirements

#### 1. Package ID / Bundle Identifier Matching

The Android `applicationId` / package name (e.g. `com.example.myapp`) and iOS `bundleIdentifier` **MUST** match the exact Package ID registered for your App in the [Perkox Publisher Dashboard](https://pub.perkox.com).

> **Warning**: If the Package ID does not match, the Offerwall API returns: `{"success": false, "message": "Invalid package_id for this offerwall"}` causing zero offers to be displayed.

#### 2. Server-Side Postbacks for Secure Rewards

> **Important**: Do **not** rely exclusively on client-side `onReward` callbacks to grant high-value rewards, as client callbacks only execute while the app is active. Always configure **Server-Side Postbacks** in the Perkox Dashboard for reliable, tamper-proof reward validation.

```
https://yourapp.com/api/perkox/postback?user_id={user_id}&amount={amount}&tx_id={tx_id}&offer_id={offer_id}&status={status}
```

***

### Troubleshooting

| Issue                                  | Cause & Solution                                                                                                                              |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Offerwall opens but shows 0 offers** | Verify that your Android `applicationId` / iOS `bundleIdentifier` exactly matches the registered Package ID in the Perkox Dashboard.          |
| **Expo Go Error**                      | Custom native modules cannot run inside standard Expo Go. Use Expo Prebuild (`npx expo run:android` / `npx expo run:ios`) or Expo Dev Client. |
| **Invalid player\_id**                 | Ensure `playerId` is not an empty string (`""`). Always pass a unique, non-empty user identifier during `PerkoxSDK.init()`.                   |

***

### Support

Need help with integration?

* **Dashboard**: [pub.perkox.com](https://pub.perkox.com)
* **Email**: <support@perkox.com>