Integrating with C/C++ projects

This is essentially the same integrating any other third-party native library & assumes you are working with platform-standard tools and project types.


1. Download the GameBench SDK

This is a .zip file available from the GameBench site. Unzip it to a safe place. The principal files contained within it are:

  • lib/GameBench.aar. The native library for Android
  • lib/GameBench.framework. The native library for iOS
  • inc/GameBench.h. The header file containing declarations for the native GameBench API.

2. Add the native libraries to your projects

For Android, assuming you are working with an Android Studio project, open the build.gradle file of your application module and add GameBench.aar to the dependencies block:

dependencies {
+   implementation(files:'/path/to/GameBench.aar')

For iOS, open your XCode project and drag GameBench.framework into the project. You should ensure the framework is marked ‘Sign & embed’ in the project properties pane.

3. Add some code

The GameBench SDK must be loaded and configured in code, and the recommended time to do so is during static initialisation very early in the process’s lifetime. Here is a simple example that uses Clang/GCC’s constructor function attribute to ensure it runs at startup.

#include "GameBench.h"

// This very simple example runs during static initialization, i.e. when
// the executable module containing this code gets loaded.

static void initGameBench(void) __attribute__((constructor (101)));
static void initGameBench(void) {

    auto gb = getGameBench(); // implicitly loads GameBench native lib

    // Set your credentials
    gb->setStringConfigItem("UploadUrl", <<YOUR UPLOAD URL>>);
    gb->setStringConfigItem("UploadEmail", <<YOUR REGISTERED EMAIL>>);
    gb->setStringConfigItem("UploadToken", <<YOUR HEX TOKEN>>);

    // Enable the automatic session. This means a session will automatically start
    // when the app is foregrounded and that session will stop and be uploaded
    // when the app moves into the background.
    gb->setIntConfigItem("AutoSession", 1);

    // Set which metrics should be captured
    gb->scheduleCapture(MetricType::FPS, 1);
    gb->scheduleCapture(MetricType::CPU, 1);
    gb->scheduleCapture(MetricType::GPU, 1);
    gb->scheduleCapture(MetricType::NET, 1);
    gb->scheduleCapture(MetricType::MEM, 1);
    gb->scheduleCapture(MetricType::POW, 5);
    gb->scheduleCapture(MetricType::BAT, 5);
    gb->scheduleCapture(MetricType::SS0, 5);


4. Build and deploy to a device

The automatic session will start recording when your app is launched. Let the app run for at least 10 seconds, as any sessions shorter than that are considered invalid and will be discarded. Send the app to the background without killing the process - i.e. use the home button or switch to a different app. The session will be uploaded while the app is backgrounded.

In your web browser open the GameBench server you specified as your upload URL, and ensure you are logged in with the same credentials. Switch to the “Sessions” tab and your session should be visible.

5. Troubleshooting

The GameBench SDK has no user interface by design and cannot display helpful messages when something goes wrong. If your session didn’t appear on the server the immediate things to check are:

  • Credentials are correct
  • Test device is connected to the internet
  • Test device can reach the GameBench server
  • Session was at least 10 seconds long
  • App gets enough time in the background to upload

If these conditions are all met then the next step is to check the device’s system log (called logcat on Android). The SDK logs errors and warnings there using the tag GBSDK. Filtering the log for that should turn up useful information.

6. Further steps

You can call GameBench APIs at any time, not just at startup. Common scenarios are :

  • To start the session when the player enters a particular level or area.
  • To record markers and tags that correspond to gameplay events.

As well as the C API used in this guide there is also a NodeJS API for controlling GameBench via Appium

Last updated on