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

# Perkox Unity SDK

The official **Perkox Offerwall SDK for Unity** enables game developers to integrate high-converting, rewarded offerwalls into mobile games for Android and iOS with native performance.

With Perkox, players can earn in-game virtual currency (coins, gems, energy) by completing offers, surveys, and rewarded actions.

***

#### Key Features

* **Single Cross-Platform C# API**: Clean, static methods for Unity game developers.
* **Native Android & iOS Power**: Powered by the official Perkox Android SDK (Kotlin) and iOS SDK (Swift/XCFramework).
* **Unity Editor Simulation (Mock Mode)**: Test your game loop, UI, and reward distribution directly inside the Unity Editor without crashes or errors.
* **Automated Dependency Resolution**: Supports Google External Dependency Manager for Unity (EDM4U) and CocoaPods.
* **Anti-Fraud & Verification**: Built-in verification and attribution tracking for maximum publisher revenue protection.

***

#### Requirements

| Requirement           | Supported Version                    |
| --------------------- | ------------------------------------ |
| **Unity Editor**      | Unity 2020.3 LTS or higher           |
| **Android**           | Android 5.0 (API Level 21) or higher |
| **iOS**               | iOS 12.0 or higher, Xcode 14+        |
| **Scripting Backend** | Mono or IL2CPP                       |

***

### Installation

#### Method 1: Unity Package Manager (UPM via Git URL) — Recommended

1. In the Unity Editor, navigate to **Window** > **Package Manager**.
2. Click the **`+`** icon in the top-left corner and select **Add package from git URL...**
3. Enter the public release repository URL:

```
https://github.com/perkoxofficial/perkox-unity-sdk-releases.git
```

*(Or specify a tag: `https://github.com/perkoxofficial/perkox-unity-sdk-releases.git#v2.0.0`)* 4. Click **Add**. Unity will automatically download and install the package into your project.

#### Method 2: `.unitypackage` Manual Import

1. Download the latest `Perkox-Unity-SDK-v2.0.0.unitypackage` from the official GitHub Releases.
2. Drag and drop the `.unitypackage` into your Unity project window (or go to **Assets** > **Import Package** > **Custom Package...**).
3. Ensure all files are checked and click **Import**.

***

### Quick Start Guide

#### 1. Initialize the SDK

Call `PerkoxSDK.Initialize()` early in your game lifecycle (for example, in your GameManager's `Awake()` or `Start()`):

```csharp
using UnityEngine;
using Perkox;
using Perkox.Models;

public class GameManager : MonoBehaviour
{
    [Header("Perkox Credentials")]
    [SerializeField] private string androidAppId = "YOUR_ANDROID_APP_ID";
    [SerializeField] private string androidSdkKey = "YOUR_ANDROID_SDK_KEY";

    [SerializeField] private string iosAppId = "YOUR_IOS_APP_ID";
    [SerializeField] private string iosSdkKey = "YOUR_IOS_SDK_KEY";

    private void Awake()
    {
#if UNITY_IOS
        string appId = iosAppId;
        string sdkKey = iosSdkKey;
#else
        string appId = androidAppId;
        string sdkKey = androidSdkKey;
#endif

        // Initialize with default or guest player ID (optional)
        PerkoxSDK.Initialize(appId, sdkKey, "player_guest_123", beta: false);

        // Register event listeners
        PerkoxSDK.OnOfferwallOpened += HandleOfferwallOpened;
        PerkoxSDK.OnOfferwallClosed += HandleOfferwallClosed;
        PerkoxSDK.OnRewardReceived += HandleRewardReceived;
        PerkoxSDK.OnOfferwallError += HandleOfferwallError;
    }

    private void OnDestroy()
    {
        // Unregister event listeners
        PerkoxSDK.OnOfferwallOpened -= HandleOfferwallOpened;
        PerkoxSDK.OnOfferwallClosed -= HandleOfferwallClosed;
        PerkoxSDK.OnRewardReceived -= HandleRewardReceived;
        PerkoxSDK.OnOfferwallError -= HandleOfferwallError;
    }

    // Event callbacks
    private void HandleOfferwallOpened()
    {
        Debug.Log("[Game] Offerwall opened. Pause audio or game timer.");
    }

    private void HandleOfferwallClosed()
    {
        Debug.Log("[Game] Offerwall closed. Resume game.");
    }

    private void HandleRewardReceived(PerkoxReward reward)
    {
        // Access reward data
        double payout = reward.GetDouble("payout", 0);
        string currency = reward.GetString("currency", "Coins");

        Debug.Log($"[Game] User earned reward: {payout} {currency}!");
        // Credit virtual currency to player balance
    }

    private void HandleOfferwallError(string error)
    {
        Debug.LogError($"[Game] Offerwall Error: {error}");
    }
}
```

***

#### 2. Set Player ID (User Identification)

When a player signs in or their unique account ID becomes known, update the SDK:

```csharp
PerkoxSDK.SetUserId("player_user_98765");
```

> **Important**: The `playerId` must NOT be empty. Always provide a unique user identifier so rewards and postbacks are accurately attributed to the player.

***

#### 3. Show the Offerwall

Call `PerkoxSDK.ShowOfferwall()` when the player taps on an "Earn Rewards" or "Offerwall" button:

```csharp
public void OnOfferwallButtonClicked()
{
    PerkoxSDK.ShowOfferwall();
}
```

***

### Critical: Package ID Matching Requirements

The Perkox backend validates incoming requests against registered App credentials (`app_id`, `sdk_key`, and `package_id`).

| Platform    | Setting in Unity                                                 | Requirement                                                                   |
| ----------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| **Android** | **Player Settings** > **Identification** > **Package Name**      | **MUST** match the Android Package ID registered in your Perkox Dashboard.    |
| **iOS**     | **Player Settings** > **Identification** > **Bundle Identifier** | **MUST** match the iOS Bundle Identifier registered in your Perkox Dashboard. |

> **Warning**: If the Package Name / Bundle ID does not match the dashboard app entry, the offerwall will return `Invalid package_id for this offerwall` and show zero offers.

***

### Platform Specific Setup

#### Android Setup

* **Minimum API Level**: 21 (Android 5.0 Lollipop).
* **Target API Level**: Android 14 (API Level 34) or latest Google Play requirement.
* If using EDM4U (External Dependency Manager for Unity), resolve dependencies via **Assets** > **External Dependency Manager** > **Android Resolver** > **Resolve**.

#### iOS Setup

* **Target SDK**: iOS 12.0 or higher.
* Post-build script (`PerkoxPostProcessBuild.cs`) automatically configures the Xcode project with Swift 5.0 and `-ObjC` linker flags.
* Run `pod install` in the generated Xcode project directory if using CocoaPods.

***

### Unity Editor Simulation (Mock Mode)

When testing inside the Unity Editor (Play Mode):

1. `PerkoxSDK.Initialize()` safely logs initialization parameters to the Unity Console.
2. Calling `PerkoxSDK.ShowOfferwall()` triggers simulated callbacks:
   * Fires `OnOfferwallOpened`
   * Dispatches a test `OnRewardReceived` callback (100 Coins)
   * Fires `OnOfferwallClosed`
3. Allows complete game loop verification without building native Android or iOS binaries.

***

### Server-Side Postback (Recommended)

For secure reward validation, configure a server-side postback URL in your Perkox Dashboard. When a player finishes an offer, Perkox sends a secure server-to-server callback:

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

Verify the postback signature with your secret key before crediting virtual currency to player balances.

***

### Support

Need help with integration?

* **Dashboard**: pub.perkox.com
* **Email**: <support@perkox.com>