Nexverse Cocos Extension Integration Guide

Installation

Step 1: Prerequisites

  1. Cocos creator 3.8.7 or later.
  2. Nexverse cocos extension - nexverse-cocos-ext.zip.
  3. An active internet connection.
  4. Account Id and config id from Nexverse publisher dashboard. Refer to the App Onboarding Guide for detailed steps to generate these identifiers.

Step 2: Import the Extension

  1. Open your Cocos project
  2. Navigate to Extension > Extension Manager
  3. Click on Import Extension File (.zip)

Step 3: Select the Extension File

Choose the nexverse-cocos-ext.zip file. The extension will load automatically.

Step 4: Verify Installation

Verify the extension installation by checking if Nexverse is enabled in the installed extensions list.

SDK Initialization

The SDK must be initialized before making any ad calls.

Basic Initialization 

  NexverseAdManager.getInstance().Initialize(this, “your-account-id”);

Configuration Options

A. Test Mode

Enables or disables Test Mode for SDK network responses. This is recommended while your app is in development mode.

  NexverseAdManager.getInstance().SetTestMode(true);

Note: Please disable test mode (set to false) before pushing your app to production.

B. Global OpenRTB Configuration

Sets the global OpenRTB (oRTB) configuration parameters used for ad requests.

  NexverseAdManager.getInstance().SetGlobalOrtbConfig('{"segment":"premium", "interests":\["gaming", "sports"\]}');

Parameters:

  • targetingParams: JSON string containing key-value pairs for targeting (e.g., user segments, interests, demographics)

Recommended Usage: Call this once during initialization to set global parameters. It can also be updated later if targeting information changes (e.g., after user login).

Set GDPR Applicability

Specifies whether the user is subject to GDPR regulations.

  NexverseAdManager.getInstance().SetSubjectToGDPR(true);

Parameters:

  • gdprConsent: Pass true if GDPR applies to the user, otherwise false

Recommended Usage: Should be called at initialization, based on the user’s region or CMP determination. Must be set before passing GDPR consent string.

Configures the SDK with the user’s GDPR consent string. This is typically obtained from a CMP (Consent Management Platform).

  NexverseAdManager.getInstance().SetGDPRConsentString("CPxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx");

Parameters:

  • gdprConsentString: The IAB-compliant GDPR consent string representing the user’s preferences

Recommended Usage: Call this method before requesting ads to ensure consent is respected. Update whenever a new consent string is obtained from the CMP.

D. COPPA Settings

Specifies whether the user is subject to COPPA (Children’s Online Privacy Protection Act) compliance.

  NexverseAdManager.getInstance().SetSubjectToCOPPA(true);

Parameters:

  • Pass true if COPPA applies to the user, otherwise false

Recommended Usage: Call during SDK initialization if your app is directed towards children under 13 or needs COPPA compliance. Once set, should not be changed during the session.

E. Location and Permission Configuration

To improve ad targeting and provide a better ad experience, set the user’s consent for sharing location information.

  NexverseAdManager.getInstance().ShareGeoLocation(true);

Behavior:

  • If location permission (ACCESS_COARSE_LOCATION or ACCESS_FINE_LOCATION) is already granted:
    • The SDK will use the device’s location information when making requests (if shouldShare = true)
  • If permission is not granted:
    • SDK will request permission when shouldShare = true
  • If shouldShare = false:
    • The SDK will stop using location data

F. SDK Initialization Callbacks

Use the ISDKCallbacks interface to handle initialization callbacks. We recommend adding this during the start method.

  export class AdManager extends Component implements ISDKCallbacks
{
    public Initialize_SDK() {
        NexverseAdManager.getInstance().Initialize(this, this.account_id);
    }
    onSdkInitialized() {
        //sdk initialized success
    }
    onSdkInitializedWithWarning(warning: string) {
        //sdk initialized success with warning
    }
    onSdkFailed(error: string) {
        //sdk initialized failed with error
    }

}

Recommendation: Proceed with showing ads only if SDK initialization was successful.

Supported Ad Formats

The Nexverse extension for Cocos supports the following ad formats:

  • Banner Ads
  • Interstitial Ads
  • Rewarded Video Ads

Banner ads are rectangular display units that occupy a portion of your app’s layout. The SDK supports both HTML and video banner formats. These ads can be placed at various positions within your app’s interface and can be configured to refresh automatically at specified intervals.

Standard Banner Sizes

Size (WxH) Description Availability Supported Type
300x50 Banner Phones and Tablets Banner
320x50 Banner Phones and Tablets Banner
320x100 Large Banner Phones and Tablets Banner
300x250 IAB Medium Rectangle Phones and Tablets Banner, Video
468x60 IAB Full-size Banner Tablets Banner
728x90 IAB Leaderboard Tablets Banner

HTML Banner Ads

HTML banners are the most common type of banner ads. They can display static images, animated content, or interactive rich media.

Configuration Parameters

Parameter Description Default Value Required
configIdAndroid Android placement ID - Yes
configIdIos iOS placement ID - Yes
adSize Banner size (e.g., 320x50) 320x50 Yes
placement Banner placement position Top No
autoRefreshSec Refresh interval in seconds 60 No
video Enable video content false No

Implementation 

  NexverseAdManager.getInstance().Create_Banner({
  _callback: BannerCallbacks
  _config_id: "banner-placement-id",
  _widthPx: 320,
  _heightPx: 50,
  _placement: BannerPlacement.Top,
  _autoRefreshSec: 60,
  _video: false
});

Implement the IBannerCallbacks interface in your component to handle banner ad events.

   OnBannerLoaded() {
        //banner loaded
    }
    OnBannerDisplayed() {
        //banner displayed
    }
    OnBannerClicked() {
        //banner clicked
    }
    OnBannerClosed() {
        //banner closed
    }
    OnBannerFailed(error: string) {
        //banner failed with error
    }
    OnBannerDestroyed() {
        //banner destroyed
    }

Video Banner Ads

Video banner ads provide an engaging way to monetize your app through video content. These ads play video content directly within a banner format.

Implementation 

  NexverseAdManager.getInstance().Create_Banner({
  _callback: BannerCallbacks
  _config_id: "banner-placement-id",
  _widthPx: 320,
  _heightPx: 250,
  _placement: BannerPlacement.Top,
  _autoRefreshSec: 60,
  _video: true
});

Note: Video banners are currently available only in 300x250 size.

Video Banner Callbacks

Implement the IBannerCallbacks interface in your component to handle banner ad events.

  BannerVideoCompleted() {
        //banner video completed
    }
    BannerVideoPaused() {
        //banner video paused
    }
    BannerVideoResumed() {
        //banner video resumed
    }
    BannerVideoUnMuted() {
        //banner video unmuted
    }
    BannerVideoMuted() {
        //banner video muted
    }

Remove Banner Ad

You can remove the active banner by using the following method:

  NexverseAdManager.getInstance().Destroy_Banner();

Limitation: Currently, only one banner ad can be displayed at a time. Multiple banners are not supported. If you require this functionality, please contact the support team.

Interstitial Ads

Interstitial ads are full-screen ads that appear at natural breaks in your app’s user flow, such as between level transitions or scene changes.

Load and Display Interstitial Ad

Call the interstitial ad loading method at an appropriate point in your application flow (e.g., between level transitions).

  NexverseAdManager.getInstance().Load_Interstitial({
  _callback: InterstitialCallbacks
  _config_id: "interstitial-placement-id",
  _format: InterstitialFormat.BANNER
});

Present the interstitial ad when it’s ready:

  NexverseAdManager.getInstance().Show_Interstitial();

Interstitial Callbacks

Implement the IInterstitialCallbacks interface in your component to handle interstitial ad events.

   OnInterstitialFailed(error: string) {
        //Interstitial load failed with error
    }
    OnInterstitialShowError(error: string) {
        //Interstitial show failed with error
    }
    OnInterstitialLoaded() {
        //Interstitial loaded
    }
    OnInterstitialDisplayed() {
        //Interstitial displayed
    }
    OnInterstitialClicked() {
        //Interstitial clicked
    }
    OnInterstitialClosed() {
        //Interstitial closed
    }

Video Interstitial Ads

If you want to restrict interstitial ads to serve only video content, use the following approach:

Load Video Interstitial 

  NexverseAdManager.getInstance().Load_Interstitial({
  _callback: InterstitialCallbacks
  _config_id: "interstitial-placement-id",
  _format: InterstitialFormat.VIDEO
});

Show Video Interstitial 

  NexverseAdManager.getInstance().Show_Interstitial();

HTML/Banner Interstitial Ads

If you want to restrict interstitial ads to serve only HTML/image content, use the following approach:

Load HTML Interstitial 

  NexverseAdManager.getInstance().Load_Interstitial({
  _callback: InterstitialCallbacks
  _config_id: "interstitial-placement-id",
  _format: InterstitialFormat.MULTI_FORMAT
});

Show HTML Interstitial 

  NexverseAdManager.getInstance().Show_Interstitial();

Rewarded Ads

Rewarded ads are a powerful monetization tool that provide value to both users and developers. They allow users to earn in-app rewards (such as virtual currency, extra lives, or premium content) in exchange for watching a video ad. This opt-in format typically sees high engagement rates and user satisfaction.

Important Note: Rewards are received only if the reward is configured in the Nexverse dashboard while setting up the ad placement.

Key Benefits

  • Higher User Engagement: Opt-in nature encourages user participation
  • Better User Experience: Value exchange creates positive user perception
  • Increased Retention: Reward mechanics improve app retention
  • Higher eCPMs: Rewarded ads typically generate higher revenue compared to other ad formats

Load and Display Rewarded Ad

Call the rewarded ad loading method at an appropriate point in your application flow (e.g., when the user selects a reward option).

  NexverseAdManager.getInstance().Load_Rewarded(this, “rewarded-placement-id”);

Present the rewarded ad when it’s ready:

  NexverseAdManager.getInstance().Show_Rewarded();

Rewarded Ad Callbacks

Implement the IRewardedCallbacks interface in your component to handle rewarded ad events and rewards.

  RewardAdFailed(error: string) {
        //Rewarded load failed with error
    }
    RewardAdShowError(error: string) {
        //Rewarded show failed with error
    }
    RewardAdLoaded() {
        //Rewarded loaded
    }
    RewardAdDisplayed() {
        //Rewarded displayed
    }
    RewardAdClicked() {
        //Rewarded clicked
    }
    RewardAdClosed() {
        //Rewarded closed
    }
    RewardAdReward(rewardJson: string) {
        //Rewarded granted with rewardJson 
    }

Building Project

Android Build

Below are the final steps to enable the Nexverse bridge for Android.

Step 1: Verify the AAR File

When you build your Android project:

  1. Open the generated build in Android Studio
  2. Verify that nexverseplugin.aar exists in the app > libs folder

Important: Ensure the AAR file is present before proceeding. If missing, rebuild the Cocos project.

Step 2: Add Dependencies

Find your Android app’s build.gradle file and add the Nexverse dependencies:

  dependencies {
  // Replace x.x.x with the latest version
  implementation("ai.nexverse:ai-nexverse-sdk-core:x.x.x")
  implementation("ai.nexverse:ai-nexverse-sdk-exo-extn:x.x.x")
}
Step 3: Locate AppActivity

Find your main AppActivity class, which is typically located at:

  <your-build-project-app>/java/com/cocos/game/AppActivity.java
Step 4: Initialize Nexverse in onCreate

In the onCreate method, add the following code to start listening to the Nexverse plugin:

  import com.nexverse.android.plugin.NexversePlugin;

public class AppActivity extends CocosActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        // Initialize your Java plugin
        NexversePlugin.getInstance().StartListeners(this);
    }
}
Step 5: Clean Up in onDestroy

In the onDestroy method, add the following code to stop listening to the Nexverse plugin:

  import com.nexverse.android.plugin.NexversePlugin;

public class AppActivity extends CocosActivity {

   @Override
    protected void onDestroy() {
        super.onDestroy();

        // SetDown your Java plugin
        NexversePlugin.getInstance().EndListeners();
    }
}
Step 6: Ready to Use

Nexverse ads are now ready to be displayed in your Android application. You can start implementing banner, interstitial, and rewarded ad placements as described in the integration guide.

iOS Build

iOS integration documentation will be added soon. Please check back for updates or contact support@nexverse.ai for the latest information.

Step 1: Verify bridge File

When you build your IOS project:

  1. Open the generated build in Xcode
  2. Verify that NexverseAdBridge folder exists in the source folder which contains .h and .m files

Important: Ensure the files are present before proceeding. If missing, rebuild the Cocos project.

Step 2: Add Dependencies

Add the Nexverse pod into the Podfile of your project as shown below.

If your project does not have Podfile then configure Cocoapods into your project first. Here is a guide.

  # Podfile
# This is the latest version, you can replace '1.0.8' with previous versions if needed.
pod 'Nexverse', '1.0.8'

After adding the pod, run the following command in your terminal:

  pod install
Step 3: Locate AppDelegate

Find your main AppDelegate class, which is typically located at:

  <your-project>/native/engine/ios/AppDelegate.mm
Step 4: Setup Nexverse Bridge in didFinishLaunchingWithOptions

In the didFinishLaunchingWithOptions method, add the following code to start listening to the Nexverse plugin callbacks:

  - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    [[NexverseAdBridge sharedInstance] setupBridge];
    return YES;
}
Step 5: Ready to Use

Nexverse ads are now ready to be displayed in your IOS application. You can start implementing banner, interstitial, and rewarded ad placements as described in the integration guide.

Support

For any issues or questions during integration, please contact us at:

We’re here to help ensure your integration is successful!