Cocos Creator Offerwall Integration: Complete SDK Guide (2026)

Cocos Creator is one of the most popular open-source game engines for mobile development, powering thousands of hyper-casual, casual, and mid-core games across iOS and Android. Yet when it comes to monetization, Cocos developers often struggle to find offerwall SDK integration guides tailored to their engine — most documentation targets Unity or native Android/iOS.

This guide closes that gap. We’ll walk through everything you need to integrate an offerwall SDK into a Cocos Creator game: from project setup and SDK initialization to showing the offerwall, handling reward callbacks, and optimizing placements for maximum ARPDAU.

Why Add an Offerwall to Cocos Creator Games?

Cocos Creator games span every genre from hyper-casual puzzle games to mid-core RPGs. What they share is a large base of non-paying users — typically 95% or more of players never make an in-app purchase. An offerwall monetizes these users by offering optional tasks (app installs, surveys, trials) in exchange for virtual currency.

For Cocos developers specifically, an offerwall SDK adds three revenue benefits:

• Higher ARPDAU: Offerwalls typically add $0.01 to $0.05 to daily ARPDAU, which is significant for free-to-play Cocos games. Check our ARPDAU benchmarks by genre to see where you should land.
• No gameplay interruption: Unlike interstitial ads, offerwalls are user-initiated — players choose to engage, so retention stays intact.
• Cross-platform consistency: A single SDK works across both the iOS and Android builds of your Cocos Creator project.

Prerequisites

Before starting the integration, make sure you have:

• Cocos Creator 3.6.0 or later (this guide uses the C++ and TypeScript bindings)
• A Perkox publisher account with your app registered (or any offerwall provider of your choice — see our monetization SDK selection guide)
• Android Studio (for Android builds) and Xcode (for iOS builds)
• Node.js and the Cocos Creator CLI installed

Step 1: Add the SDK to Your Cocos Creator Project

The Perkox offerwall SDK provides native Android (AAR) and iOS (framework) packages that you bridge into Cocos Creator via C++ bindings. Here’s the setup:

Android Setup

1. Download the Perkox SDK AAR file from your publisher dashboard.

2. Place the AAR in your project’s native/engine/android/app/libs/ directory.

3. Open build.gradle (Module: app) and add:

dependencies {
    implementation files('libs/perkox-offerwall.aar')
    implementation 'com.google.android.gms:play-services-base:18.2.1'
}

4. Sync Gradle and verify the build compiles.

iOS Setup

1. Download the Perkox iOS framework.

2. Drag the framework into your Xcode project’s “Frameworks, Libraries, and Embedded Content” section.

3. Ensure “Embed and Sign” is selected for the framework.

4. Add the required system frameworks: StoreKit, WebKit, and AdSupport.

Step 2: Initialize the SDK on App Launch

Initialize the offerwall SDK as early as possible in your app’s lifecycle — ideally in the onLoad method of your main scene or the application entry point. This ensures the offerwall is ready to display whenever the user requests it.

Create a C++ bridge file (or use TypeScript if you’re using Cocos Creator’s scripting layer):

#include "PerkoxOfferwall.h"

void AppDelegate::applicationDidFinishLaunching() {
    // Initialize with your app key
    PerkoxOfferwall::initialize("YOUR_APP_KEY", "YOUR_USER_ID");
    
    // Set reward callback
    PerkoxOfferwall::setRewardCallback([](int rewardAmount, const std::string& rewardName) {
        // Credit the user's virtual currency
        // This runs on a background thread — dispatch to main
        cocos2d::Director::getInstance()->getScheduler()->performFunctionInCocosThread([=]() {
            GameManager::getInstance()->addCurrency(rewardAmount);
            UIManager::getInstance()->showRewardToast(rewardAmount, rewardName);
        });
    });
}

The USER_ID should be a unique identifier for each player — typically your game’s internal user ID. This is critical for server-side reward validation, which prevents fraud and ensures rewards are only credited for genuine completions.

Step 3: Show the Offerwall

The offerwall should be shown in response to a user action — never automatically. The best placements are inside your in-game store, as a navigation tab, or as a contextual prompt when users run out of currency. For a detailed placement strategy, see our offerwall placement guide.

void StoreScene::onEarnFreeCoinsClicked() {
    if (PerkoxOfferwall::isReady()) {
        PerkoxOfferwall::showOfferwall();
    } else {
        // SDK still loading — show a fallback or retry
        UIManager::showMessage("Offers loading, please try again in a moment.");
    }
}

The isReady() check is important: the SDK needs a few seconds after launch to fetch the offer catalog from the server. If you call showOfferwall() before it’s ready, nothing will display.

Step 4: Handle Rewards with Server-Side Validation

Never credit rewards client-side. A fraudulent user could easily inject fake reward callbacks. Instead, configure a server-to-server postback endpoint that receives reward notifications from the offerwall provider, validates them, and then credits the user’s account.

The flow works like this:

1. User completes an offer (installs an app, completes a survey, etc.)
2. The offerwall provider sends a postback to your server: GET https://yourserver.com/reward?user_id=X&amount=50&transaction_id=ABC123
3. Your server validates the transaction ID (to prevent duplicates), checks the user exists, and credits the currency
4. On the client side, the reward callback fires — but you only show the UI animation, the actual credit happened on the server

This architecture is explained in detail in our server-side validation guide and is the same pattern used across all our SDK integrations, including Unity and Android.

Step 5: Configure Virtual Currency Rewards

Reward design is critical to offerwall performance. If rewards are too low, users won’t engage; if too high, you cannibalize IAP revenue. The general rule: offerwall rewards should be worth 20 to 50% of your cheapest IAP package.

For Cocos Creator games, common virtual currencies include coins, gems, energy, or lives. Configure the exchange rate in your Perkox dashboard so that 1 cent of real revenue equals a meaningful amount of in-game currency. For a deep dive, read our reward design guide.

Step 6: Test the Integration

Before going live, test the full reward flow:

1. Launch your Cocos Creator game in the simulator or on a device
2. Navigate to your offerwall entry point and open the offerwall
3. Complete a test offer (Perkox provides test offers in sandbox mode)
4. Verify the postback arrives at your server
5. Confirm the reward is credited and the UI updates correctly

Use the integration checklist to make sure you haven’t missed anything before launch.

Optimizing Offerwall Performance in Cocos Creator

Once your offerwall is live, track these key metrics:

• Open rate: What percentage of DAU open the offerwall? Aim for 15 to 30%.
• Completion rate: Of those who open it, how many complete an offer? Aim for 5 to 15%.
• ARPDAU contribution: How much daily revenue comes from the offerwall? Use our ARPDAU calculation guide to measure this precisely.

If open rates are low, revisit your placement — the offerwall should be visible in the store menu, not buried in settings. If completion rates are low, your rewards may be too small or your offer catalog too thin for your user geos.

Cocos Creator-Specific Tips

Cocos Creator has some quirks worth noting for offerwall integration:

• Thread safety: Reward callbacks from native SDKs arrive on background threads. Always dispatch to the Cocos main thread before touching any game state or UI, as shown in the code example above.
• Scene transitions: If the user is mid-offer when a scene changes, cache the reward callback and process it in the new scene. Don’t try to show UI during a transition.
• Build settings: For Android, ensure ProGuard/R8 doesn’t strip the SDK classes. Add -keep class com.perkox.** { *; } to your ProGuard rules.
• iOS App Transport Security: The offerwall loads web content, so ensure your ATS policy allows HTTPS loads, or add an exception domain for the offerwall CDN.

Common Issues and Solutions

Offerwall doesn’t appear on tap: Check that initialize() was called and isReady() returns true. The SDK needs network access — test on a real device, not just the simulator.

Rewards not credited: Verify your postback endpoint is live and returning HTTP 200. Check server logs for incoming postback requests. If using a custom user ID, ensure it matches between SDK initialization and your server.

Build errors on Android: Make sure the AAR is in the correct libs/ directory and that Gradle syncs successfully. Check for version conflicts with Google Play Services.

Key Takeaways

• Cocos Creator games can integrate an offerwall SDK via native Android/iOS packages with C++ bindings
• Initialize early, show on user action, and always validate rewards server-side
• Target 20 to 50% of your cheapest IAP value for offerwall rewards
• Track open rate, completion rate, and ARPDAU contribution to measure success
• Handle thread safety carefully — Cocos requires main-thread dispatch for UI updates

Ready to add an offerwall to your Cocos Creator game? Get started with Perkox — integrate in under 10 minutes with full Cocos Creator support.

Frequently Asked Questions