Cocos2d-x integration guide

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

New to Bugsnag? Create an account

Installation

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:

if(ANDROID OR APPLE)
    add_subdirectory(bugsnag)
    target_link_libraries(${APP_NAME} bugsnag-cocos2dx)
endif()

The next steps depend on your supported platforms.

Android

Add the Bugsnag plugin to the bottom of proj.android/settings.gradle:

// ...
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 proj.android/app/build.gradle:

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. You can find your API key when creating a project in your Bugsnag dashboard, or later from your Project Settings page. In order to capture as many errors as possible on each platform, initialize at the closest point to the app launching as possible.

Android

Configure your API key in the <application> tag of your App Manifest file, located at proj.android/app/src/main/AndroidManifest.xml.

<application ...>
  <meta-data android:name="com.bugsnag.android.API_KEY"
             android:value="YOUR-API-KEY-HERE"/>
</application>

Then import and initialize Bugsnag in AppActivity.java:

import com.bugsnag.android.Bugsnag;
import com.bugsnag.android.BugsnagCocos2dxPlugin;

public class AppActivity extends Cocos2dxActivity {

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

        if (!isTaskRoot()) {
            return;
        }
        BugsnagCocos2dxPlugin.register();
        Bugsnag.init(this);
        // ...
    }
}

iOS

Import and initialize Bugsnag in AppController.mm:

#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"];
    // ...
}

macOS

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

#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"];
    // ...
}

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(ex);

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:

  • A full stacktrace
  • Device model and OS version
  • Release stage (production, debug, etc)
  • The version of Cocos2d‑x used to build the application
  • Free disk space at the time the report is sent
  • A device- and vendor-specific identifier
  • Additional platform-specific information

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@example.com", "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