Offerwall SDK Integration: iOS Complete Tutorial

Prerequisites

• Perkox publisher account
• App ID and SDK Key
• iOS 13.0+, Swift 5.7+, Xcode 14+

Step 1: Add the SDK

Download the Perkox iOS SDK. In Xcode: File → Add Package Dependencies → Add Local → select the extracted SDK folder containing PerkoxOfferwall.xcframework.

After adding the package, verify that the framework is linked to your app target under General → Frameworks, Libraries, and Embedded Content. Set the embed mode to Embed & Sign to ensure the framework is bundled correctly with your app binary at build time.

If your project uses SPM (Swift Package Manager) with a remote URL instead of a local package, you can add the SDK via File → Add Package Dependencies and paste the Perkox package URL from your dashboard. Xcode resolves and downloads the latest tagged release automatically.

Step 2: Initialize and Launch

Initialize the Perkox offerwall in your view controller’s viewDidLoad or viewDidAppear method. Pass a unique playerId for each user so rewards can be tracked server-side via postback.

import PerkoxOfferwall

let offerwall = PerkoxOfferwall.create(
    appId: "YOUR_APP_ID",
    sdkKey: "YOUR_SDK_KEY",
    playerId: "Player_123"
)
offerwall.launch(viewController: self)

The create method returns a singleton instance you can reuse. Store it as a property on your view controller or a shared manager class so you can present the offerwall from any screen without reinitializing.

Step 3: Handle Events

The SDK fires two key callbacks: onReward when a user earns a reward, and onClose when the offerwall is dismissed. Both callbacks fire on a background thread, so wrap UI updates in DispatchQueue.main.async.

offerwall.onReward = { reward in
    DispatchQueue.main.async {
        let amount = reward["amount"] as? Double ?? 0
        let status = reward["status"] as? String ?? "?"
        print("Reward: \(amount), Status: \(status)")
        // Update in-game currency or show a reward toast
        self.playerBalance += amount
        self.showRewardToast(amount: amount)
    }
}
offerwall.onClose = {
    DispatchQueue.main.async { print("Offerwall closed") }
}

SDK callbacks = UI feedback only. Server postback = actual reward credit. Always validate rewards on your backend before granting currency, items, or premium content. The SDK callback can fire before the postback arrives, so treat it as a UI hint, not a source of truth.

Step 4: Configure Postback

Set your postback URL in the Perkox Publisher Dashboard. Handle all four statuses: pending, approved, rejected, reversed. A robust postback handler looks like this:

// Server-side handler (Node.js example)
app.post("/perkox/postback", (req, res) => {
    const { player_id, amount, status, transaction_id, signature } = req.body;
    
    // Verify signature
    if (!verifySignature(req.body, process.env.PERKOX_SECRET)) {
        return res.status(403).send("Invalid signature");
    }
    
    switch (status) {
        case "approved":
            grantCurrency(player_id, amount, transaction_id);
            break;
        case "reversed":
            reverseCurrency(player_id, amount, transaction_id);
            break;
        case "rejected":
            logRejection(player_id, transaction_id);
            break;
        case "pending":
            logPending(player_id, amount, transaction_id);
            break;
    }
    res.status(200).send("OK");
});

Idempotency is critical: always check transaction_id against your database before granting rewards. Duplicate postbacks can arrive during network retries, and granting twice means lost revenue.

Step 5: Test Before Launch

Use the Perkox dashboard test mode to verify the full flow: offerwall presentation, reward callback, and postback delivery. Send a test conversion from the dashboard and confirm your server receives and processes it correctly. Only switch to live mode after end-to-end validation.

Troubleshooting

No such module ‘PerkoxOfferwall’: Verify package was added to your target. Clean build folder (Cmd+Shift+K). Check that the xcframework is embedded, not just linked.

Offerwall not loading: Verify appId/sdkKey. Check internet. Confirm app is active in dashboard. Check that your app’s Info.plist includes the required App Transport Security settings.

Callbacks not firing: Ensure the offerwall instance is retained (not garbage collected). Store it in a strong property, not a local variable.

Postback not received: Verify the URL is reachable from the public internet. Check firewall rules. Confirm your endpoint returns HTTP 200. Use the dashboard’s postback tester to send a test ping.

Why This Matters

iOS users have higher average revenue per user (ARPU) than Android in most genres, but they also expect polished, native experiences. A correctly integrated SDK ensures the offerwall loads fast, callbacks fire reliably, and rewards are validated server-side — all of which directly impact your eCPM and retention. Skipping server-side validation or mishandling postbacks can result in fraudulent reward claims, duplicate credits, or lost revenue.

Key Takeaway

Integration takes under 15 minutes: add the framework, initialize with your credentials, wire up callbacks for UI, and configure a server-side postback handler with signature verification and idempotency checks. Test in dashboard mode before going live. Always treat SDK callbacks as UI hints and the postback as the source of truth for reward crediting.

Get started with Perkox →