Cocos2d-x integration guide

Add Bugsnag to your Cocos2d-x 3.1+ games for Android, iOS, and macOS.

New to Bugsnag? Create an account


Download the latest bugsnag-cocos2dx release and unzip it into a new directory named bugsnag in your app’s root directory.

Add the release directory at the bottom of your root CMakeLists.txt file and link the dependency:

    target_link_libraries(${APP_NAME} bugsnag-cocos2dx)

The next steps depend on your supported platforms.


Add the Bugsnag plugin to the bottom of

// ...
include ':bugsnag-cocos2dx'
project(':bugsnag-cocos2dx').projectDir = new File(settingsDir, '../bugsnag/android/bugsnag-plugin-android-cocos2dx')

Add flatDir as a repository and the Bugsnag project as a dependency to your Module Gradle Settings in

repositories {
    flatDir {
        dirs '../../bugsnag/android/libs'
dependencies {
    // ...
    implementation project(':bugsnag-cocos2dx')

iOS and macOS

If you are using Cocos2d‑x v3.x, the Bugsnag library will need to be added to your Xcode project in proj.ios_mac. This step is not required for Cocos2d‑x v4+.

  1. Select your Xcode project’s Build Phases tab and drag libbugsnag-cocos2dx-{platform}.a for your platform from bugsnag/cocoa/ to Link Binary with Libraries.
  2. Select your Xcode project’s Build Settings tab, then:
    • Add $(SRCROOT)/../bugsnag/include to Header Search Paths
    • Add $(SRCROOT)/../bugsnag/cocoa to Library Search Paths

Basic configuration

To identify your app in the Bugsnag dashboard, you’ll need to configure your Bugsnag API key.

In order to capture as many errors as possible on each platform, initialize at the closest point to the app launching as possible.


Configure your API key in the <application> tag of your App Manifest file, located at

<application ...>
  <meta-data android:name=""

You can find your API key in Project Settings from your Bugsnag dashboard.

Then import and initialize Bugsnag in


public class AppActivity extends Cocos2dxActivity {

    protected void onCreate(Bundle savedInstanceState) {

        if (!isTaskRoot()) {
        // ...


Import and initialize Bugsnag in

#import <BugsnagCocos2dx/cocoa/Bugsnag.h>
#import <BugsnagCocos2dx/cocoa/BugsnagCocos2dxPlugin.h>
#import <cocos/cocos2d.h>

- (BOOL)application:(UIApplication *)application 
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [BugsnagCocos2dxPlugin registerWithCocos2dVersion:cocos2d::cocos2dVersion()];
    [Bugsnag startBugsnagWithApiKey:@"YOUR-API-KEY-HERE"];
    // ...

You can find your API key in Project Settings from your Bugsnag dashboard.


Rename main.cpp to in Xcode and your CMakeLists.txt file and import and initialize Bugsnag in

#import <BugsnagCocos2dx/cocoa/Bugsnag.h>
#import <BugsnagCocos2dx/cocoa/BugsnagCocos2dxPlugin.h>

int main(int argc, char *argv[])
    [BugsnagCocos2dxPlugin registerWithCocos2dVersion:cocos2d::cocos2dVersion()];
    [Bugsnag startBugsnagWithApiKey:@"YOUR-API-KEY-HERE"];
    // ...

You can find your API key in Project Settings from your Bugsnag dashboard.

Further configuration

If you’d like to configure Bugsnag further, check out the configuration options reference for Android or iOS and macOS.

Showing full stacktraces

Uploading mapping files for Android

If you have enabled ProGuard or use the NDK, you will need to send mapping files to Bugsnag in order to deobfuscate Android stack traces. Adding the Bugsnag Gradle Plugin to your exported Gradle project will perform this task automatically.

Uploading debug symbol maps (dSYMs) for iOS

Send debug symbol (dSYM) files to Bugsnag in order to symbolicate native iOS stack traces and show the file and line numbers where an error occurred. Our iOS symbolication guide provides details on how to automate this process. By default, Cocos2d‑x does not use Bitcode.

Reporting unhandled errors

At this point, Bugsnag should be installed and configured, and any unhandled exceptions will be automatically detected and should appear in your Bugsnag dashboard.

Reporting handled errors

If you would like to send handled errors to Bugsnag, you can pass any std::exception or a name and message to the notify function:

#include <BugsnagCocos2dx/Bugsnag.hpp>

// ...


Bugsnag::notify("Authorization failed", "Invalid username value");

Sending diagnostic data

Automatically captured diagnostics

Bugsnag will automatically capture and attach the following diagnostic data to every exception report:

  • Full stack traces for all threads.
  • App state including running time and time in foreground.
  • Build information including name, version/build and release stage.
  • Device specification including model, OS version and total memory.
  • System state including orientation, free memory, available disk space and battery level.

For more information see Automatically captured data.

Attaching custom diagnostics

It is often helpful to send us additional application-specific diagnostic data, for example the name of a subsystem in which an exception occurred. If you would like to add custom data to your Bugsnag error reports, you can use the addMetadata method. Custom data is displayed inside tabs on each exception on your Bugsnag dashboard.

#include <BugsnagCocos2dx/Bugsnag.hpp>

// ...

Bugsnag::addMetadata("system", "subsystem", "player mechanics");

Logging breadcrumbs

In order to understand what happened in your application before each crash, it can be helpful to leave short log statements that we call breadcrumbs. The last several breadcrumbs are attached to a crash to help diagnose what events lead to the error.

Automatically captured breadcrumbs

By default, Bugsnag captures common events such as:

  • Low memory warnings
  • Device rotation (if applicable)
  • Menu presentation
  • Screenshot capture (not the screenshot itself)
  • Undo and redo
  • Table view selection
  • Window visibility changes
  • Non-fatal errors

Attaching custom breadcrumbs

To attach additional breadcrumbs, use the leaveBreadcrumb function:

#include <BugsnagCocos2dx/Bugsnag.hpp>

// ...

Bugsnag::leaveBreadcrumb("Button clicked", BreadcrumbType.Navigation, 
                         {{"panel", panelName}, {"should restart", "no"});

Identifying users

Bugsnag helps you understand how many of your users are affected by each error. In order to do this, we send along a user ID with every exception. By default we will generate a unique ID and send this ID along with every exception from an individual device.

If you would like to override this identifier or add additional information, use setUser:

#include <BugsnagCocos2dx/Bugsnag.hpp>

// ...

Bugsnag::setUser("id123", "", "User Name");

Session tracking

Bugsnag tracks the number of “sessions” that happen within your application. This allows you to compare stability scores between releases and helps you to understand the quality of your releases.

Sessions are captured and reported by default. This behaviour can be disabled using a configuration option on Android and iOS/macOS.

Using this option, Bugsnag will report a session each time:

  • The app is launched
  • The app enters the foreground for the first time in 60 seconds

If you want control over what is deemed a session, you can switch off automatic session tracking and manage the session lifecycle using startSession, pauseSession, and resumeSession:

#include <BugsnagCocos2dx/Bugsnag.hpp>

// ...

Bugsnag::startSession(); // Start a new session

Bugsnag::pauseSession(); // Pause the current session

Bugsnag::resumeSession(); // Resume a paused session

Next steps