Perkox Offerwall SDK for iOS

The Perkox Offerwall SDK for iOS is a lightweight SDK that allows iOS app developers to integrate the Perkox Offerwall directly into their application.

With Perkox, users can earn in-app rewards by completing offers, surveys, and other rewarded engagement activities.

The SDK is designed to provide a simple Swift integration flow while giving publishers access to rewarded monetization, analytics, and secure server-side reward validation.

---

Requirements

Before integrating the Perkox iOS SDK, make sure your project meets the following requirements:

Requirement	Version
iOS Deployment Target	13.0+
Swift	5.7+
Xcode	14.0+
Architectures	arm64 for device, arm64 + x86_64 for simulator

---

Installation

Step 1: Download the SDK

Download the latest iOS SDK release .zip file from the official Perkox GitHub Releases page or from the package provided by the Perkox team.

After extracting the .zip file, you should see a folder similar to:

perkox-ios-sdk-release-{version}/
├── Package.swift
└── PerkoxOfferwall.xcframework/
    ├── Info.plist
    ├── ios-arm64/
    │   └── PerkoxOfferwall.framework/
    └── ios-arm64_x86_64-simulator/
        └── PerkoxOfferwall.framework/

The folder contains a local Swift Package and the bundled PerkoxOfferwall.xcframework.

---

Step 2: Add the Package to Your Xcode Project

In Xcode, add the Perkox SDK as a local Swift Package.

Follow these steps:

1. Open your project in Xcode

2. Go to File → Add Package Dependencies…

3. In the bottom-left of the dialog, click Add Local…

4. Navigate to the extracted folder:

perkox-ios-sdk-release-{version}

1. Select the folder and click Add Package

2. In the next prompt, make sure your app target is checked

3. Click Add Package again

---

Important Installation Tip

Place the extracted SDK folder somewhere stable before adding it to Xcode.

Recommended location:

your-ios-app/
├── YourApp.xcodeproj
└── perkox-ios-sdk-release-{version}/

Xcode references local Swift Packages by path. If the SDK folder is moved after being added, Xcode may not be able to find the package.

---

Quick Start

After installing the SDK, you can launch the Perkox Offerwall using your App ID, SDK Key, and a unique Player ID.

You can find your App ID and SDK Key inside the Perkox Publisher Dashboard.

---

Basic Swift Implementation

import UIKit
import PerkoxOfferwall

class ViewController: UIViewController {

    private func showOfferwall() {
        let offerwall = PerkoxOfferwall.create(
            appId: "YOUR_APP_ID",       // Your App ID
            sdkKey: "YOUR_SDK_KEY",     // Your SDK Key
            playerId: "Player_123"      // Unique player ID
        )

        offerwall.launch(viewController: self)
    }
}

---

API Reference

PerkoxOfferwall

PerkoxOfferwall is the main entry point for creating and launching the Perkox Offerwall.

Method	Parameters	Returns	Description
create()	appId: String, sdkKey: String, playerId: String	Offerwall	Creates a new Offerwall instance

---

Offerwall

The Offerwall object is used to launch the offerwall and listen to basic offerwall events.

Method / Property	Type	Description
launch(viewController:)	UIViewController	Presents the offerwall modally from the given view controller
onReward	(([String: Any?]) -> Void)?	Callback triggered when a reward event is received
onClose	(() -> Void)?	Callback triggered when the offerwall is closed

---

Listening to Events

You can listen to reward and close events by setting callbacks before launching the offerwall.

Important Reward Handling Notice

Do not rely only on SDK reward callbacks to grant rewards to users.

SDK callbacks only work while the offerwall is active inside the app. For accurate and reliable reward processing, rewards should be handled server-side using the Postback URL configured in your Perkox dashboard.

Recommended reward flow:

User completes offer
→ Perkox validates conversion
→ Perkox sends postback to your server
→ Your backend verifies the event
→ Your backend credits the user

Use SDK callbacks mainly for UI feedback, logs, or temporary in-app updates.

The onReward callback may be triggered multiple times for the same transaction with different statuses, such as pending, approved, rejected, or reversed.

---

Full Swift Example with Callbacks

import UIKit
import PerkoxOfferwall

class ViewController: UIViewController {

    private func showOfferwall() {
        let offerwall = PerkoxOfferwall.create(
            appId: "YOUR_APP_ID",
            sdkKey: "YOUR_SDK_KEY",
            playerId: "Player_123"
        )

        // Handle reward events
        offerwall.onReward = { reward in
            DispatchQueue.main.async {
                let amount = reward["amount"] as? Double ?? 0
                let status = reward["status"] as? String ?? "?"
                let txid = reward["txid"] as? String ?? "?"
                let playerId = reward["player_id"] as? String ?? "?"

                print("Reward received! Amount: \(amount), Status: \(status)")
            }
        }

        // Handle offerwall close event
        offerwall.onClose = {
            DispatchQueue.main.async {
                print("Offerwall closed")
            }
        }

        // Launch the offerwall
        offerwall.launch(viewController: self)
    }
}

---

Reward Data Fields

When a reward event is received, the SDK may return the following fields:

Field	Type	Description
amount	Double	Reward amount
txid	String	Unique transaction ID
status	String	Reward status
player_id	String	Player ID passed during SDK initialization

---

Reward Statuses

Status	Description	Recommended Action
pending	Reward is being reviewed or processed	Do not grant final reward yet
approved	Reward has been validated	Credit the user server-side
rejected	Reward was not approved	Do not credit the user
reversed	Previously approved reward was reversed	Adjust or remove the reward if already credited

---

Player ID

The playerId should be a unique and stable identifier for the user inside your app.

Examples:

player123
user_98765
account_45678

The Player ID is important because it allows your backend to identify which user should receive the reward.

Best practices:

• Use a stable internal user ID

• Do not use random temporary values

• Do not use sensitive personal information

• Make sure the same user keeps the same Player ID across sessions

---

Reward Validation Best Practice

For production integrations, Perkox recommends using server-side reward validation through postbacks.

The SDK callback is useful for listening to events inside the app, but the final reward credit should happen on your backend.

Recommended production setup:

App launches Perkox Offerwall with playerId
→ User completes an offer
→ Perkox validates conversion
→ Perkox sends postback to publisher backend
→ Publisher backend checks txid and status
→ Publisher backend credits the user

This helps prevent duplicate rewards, missed rewards, and client-side manipulation.

---

Troubleshooting

1. No such module 'PerkoxOfferwall' Build Error

Check the following:

• Make sure you selected your app target when the Add Package prompt appeared

• Go to your target settings

• Open General → Frameworks, Libraries, and Embedded Content

• Verify that PerkoxOfferwall is listed

• Clean the build folder using Product → Clean Build Folder

• Rebuild the project

Shortcut:

Cmd + Shift + K

---

2. Xcode Cannot Find the Local Package After Moving Files

Xcode references local Swift Packages by path.

If you move the SDK folder after adding it, the package reference may break.

To fix this:

1. Remove the package from the project

2. Go to File → Packages → Reset Package Caches

3. Re-add the package from its new location

Best practice:

Keep the extracted SDK folder next to your .xcodeproj file or inside a stable /SDKs folder.

---

3. Offerwall Not Loading Content

Check the following:

• Verify that your appId is correct

• Verify that your sdkKey is correct

• Check the device internet connection

• Make sure the playerId is not empty

• Make sure the app/property is active inside the Perkox dashboard

• Test on a real device if simulator behavior is inconsistent

---

4. Reward Callback Not Triggering

Possible reasons:

• The offerwall was closed before the event was returned

• The conversion is still pending

• The reward was processed server-side through postback

• The user did not complete the offer requirements

• The transaction status has not changed yet

For production reward handling, always rely on server-side postbacks.

---

Changelog

v1.0.0

Initial iOS SDK release.

Included:

• Lightweight iOS offerwall integration

• Local Swift Package support

• PerkoxOfferwall.xcframework

• Basic Swift implementation

• Reward callback support

• Close callback support

• Server-side postback recommendation

---

Support

For questions, issues, or feature requests, contact:

[email protected]

When contacting support, include:

• App ID

• SDK version

• iOS version

• Xcode version

• Device model

• Error logs if available

• Description of the issue

• SDK Integration └── iOS SDK