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()):

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:

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:

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: [email protected]