SDK User Guide

Latest Version: 0.6.0
Status: This version should not be included into release or release candidate games. v0.6 is suitable for Alpha/Beta testing

Table of contents

  1. What is the GameBench SDK?
  2. Installation and configuration
    1. Supported platforms
    2. Supported Unity versions
    3. Installation process
    4. SDK configuration
  3. Features
    1. Performance metrics
    2. Markers
    3. Life-cycle API
    4. Tags
  4. SDK Overhead
  5. Known issues
  6. Troubleshooting
  7. Uninstallation

What is the GameBench SDK?

The GameBench SDK provides an ability to capture and collect device performance information during a game session for games developed using the Unity game engine. All the data is uploaded to the GameBench server and can be viewed via GameBench Web Dashboard or accessed via GameBench API.

Installation and configuration

Supported platforms

  • iOS 10 or above
  • Android 6.0 or above (armeabi-v7a and ARM64)
  • We’ve tested the SDK across a multitude of devices, see our device list.

Supported Unity versions

  • Unity 2017/18/19/20 (beta)
  • Unity Scripting Backend: IL2CPP and Mono
  • Unity Scripting Runtime Version: All stable .NET versions

Installation process

The Installation of the GameBench SDK is a very easy process and it shouldn’t take more than a few minutes to get started. You just need to perform the following steps:

  1. Open Unity Editor with your game project and navigate to the project tab.
  2. Drag and drop the “gamebench.UnityPackage” package into the unity project. (NOTE: SDK currently is in the beta stage. If you need access, please get in touch with the GameBench support team).
  3. The following dialog will appear. Ensure that all items are selected and then click import.
    sdk_import_files
  4. You will be prompted to configure the SDK. You can configure it now or do it later. How to configure SDK?.

SDK configuration

There are 2 options to configure the GameBench SDK:

  1. Using the Configuration tab. There are 2 ways to open the tab:
    1. In the Unity Editor menu select “GamebenchSDK->Configure”.
    2. Configuration settings can also be opened when the GameBench SDK package is imported.
  2. Using the Configuration API

Configuration tab

sdk_configuration_tab

Core settings
  • “GameBench Backend URL” - Base URL address of the server where performance data will be stored.
  • “Email Address” - we suggest using a separate account to store sessions captured via the GameBench SDK.
  • “SDK Token” - API token. See the API token documentation for more details.
Activate
  • “Enable Gamebench SDK” - When enabled the SDK will capture performance metrics during the whole game session.

Configuration API

The GameBench SDK provides an ability to set “Gamebench Backend URL” via the SDK API.

Please find the description and example below:

namespace Gamebench.Sdk
{
    public delegate void UploadCallback(bool success, string errorReason="");
    interface IGamebenchSDK
    {
        void SetEndPointUri(string serverEndpoint);
     }
 
    /* *API example:        
     *  Gamebench.Sdk.IGamebenchSDK sdk = Gamebench.Sdk.GamebenchSDK.GetInstance();
     *  sdk.SetEndPointUri("https://xxx.xxx.xxx.xxx/endpoint");
     * */
}

Features

Performance metrics

The GameBench SDK captures performance data for every gaming session. Each performance session can contain the following features:

  1. FPS
  2. GPU
  3. Memory
  4. Battery

FPS

All sessions captured by the GameBench SDK have Frames Per Second data. More information on FPS analysis.

GPU

The GameBench SDK can capture GPU usage data on many Android devices with Mali GPU as well as devices running iOS and targeting Metal. Support is not available for OpenGLES API.
List of GPU supported processors and devices.
More information on GPU analysis.

Memory

All sessions captured by the GameBench SDK have Memory Usage metrics.
More information on Memory metrics and analysis.

Battery

All sessions captured by the GameBench SDK have Battery Usage metrics.
More information on Battery metrics and analysis.

CPU

All sessions captured by the GameBench SDK have CPU Usage metrics.
More information on CPU metrics and analysis.

Android

CPU usage values are normalised. We’ve verified the values with the Android Studio profiler.

iOS

CPU usage values are not normalised. We’ve verified the values using the debug gauges in Xcode.

Markers

To segregate the performance data of the specific areas in your gameplay like game levels or battles, the GameBench SDK provides markers functionality. There are 2 ways to create Markers during the gameplay:

  1. Manually set programmatic markers
  2. Automatic marker creation when Unity scenes change

SDK Programmatic markers

SDK Programmatic markers provide an ability to segregate specific regions in a game by setting “in” and “out” points on specific game events. For example, if you want to isolate device performance data during a particular game level, you can set “in” marker when the level begins and “out” marker when the level is completed.

Please find below the API example:

namespace Gamebench.Sdk
{
    public delegate void UploadCallback(bool success, string errorReason="");
    interface IGamebenchSDK
    {
        void MarkerEventStart(string markerName);
        void MarkerEventStop(string markerName);
    }
 
    /* *API example:        
     *  Gamebench.Sdk.IGamebenchSDK sdk = Gamebench.Sdk.GamebenchSDK.GetInstance();
     *  sdk.MarkerEventStart("Level 3");
     *  ...
     *  sdk.MarkerEventStop("Level 3");
     * */
}

Unity scene change markers

For games where game logic is organized using Unity scenes, the GameBench SDK can segregate performance data for each scene automatically. The GameBench SDK can detect when Unity scenes change and create markers for each scene.

To enable this feature, please use the following method:

namespace Gamebench.Sdk
{
    public delegate void UploadCallback(bool success, string errorReason="");
    interface IGamebenchSDK
    {
        void SetSceneChangeAutoMarkerCreate(bool setState); //if set true, scene change will automatically trigger marker
    }
 
    /* *API example:        
     *  Gamebench.Sdk.IGamebenchSDK sdk = Gamebench.Sdk.GamebenchSDK.GetInstance();
     *  sdk.SetSceneChangeAutoMarkerCreate(true);
     * */
}

Life-cycle API

The life-cycle API allows developers to control the life-cycle of the GameBench SDK from Unity. As opposed to the automatic mode which automatically starts, stops and uploads sessions.

To enable, please check “Manual control of SDK life-cycle” within the GameBenchSDK configuration.

API

    public delegate void UploadCallback(bool success, string errorReason = "");

    public interface IGamebenchSDKLifeCycle : IGamebenchSDK, IGamebenchShared
    {
        GBStatus InitSDK(); // init sdk environment
        GBStatus StartPerformanceCapture(IDictionary<MetricType, bool> metrics=null); 
        GBStatus StopPerformanceCapture(); // stop collecting performance data
        GBStatus CleanPerformanceData(); // clean up performance data
        GBStatus UploadPerformanceData(UploadCallback callback = null); // flush performance data to server
        GBStatus DestroySDK(); // destroy sdk environment and release resources
        GBStatus StartMarker(string markerName);
        GBStatus StopMarker(string markerName);
        GBStatus ConfigCaptureFrequency(IDictionary<MetricType, float> metrics);
    }

Life-cycle usage example

Gamebench.Sdk.IGamebenchSDKLifeCycle sdk = Gamebench.Sdk.GamebenchSDKLifeCycle.GetInstance();
sdk.InitSDK();

API reference

GBStatus InitSDK(): Initialize the SDK runtime in your game.

StartPerformanceCapture(IDictionary<MetricType, bool> metrics=null): Start session to capture performance metrics. Metrics to be captured can be specified via the dictionary argument.

StopPerformanceCapture(): Stop session, the session will be stored on the test device.

CleanPerformanceData(): Clean up all session data stored on the test device.

UploadPerformanceData(UploadCallback callback = null): Upload the current local session data to the endpoint configured in the UI. After that, the uploaded session will be removed from the test device. The callback argument will be invoked once the upload is complete.

DestroySDK(): Destroy SDK runtime in your game.

StartMarker(string markerName): Start marker at current time with name.

StopMarker(string markerName): Stop marker at current time with name.

ConfigCaptureFrequency(IDictionary<MetricType, float> metrics): Configure capture frequency for each metric. Value in dictionary is specified in seconds.

Examples

Start session to capture FPS and GPU but not Power, Memory or Battery:
Gamebench.Sdk.IGamebenchSDKLifeCycle sdk = Gamebench.Sdk.GamebenchSDKLifeCycle.GetInstance();
sdk.InitSDK();
var captureList = new Dictionary<MetricType, bool>();
captureList.Add(MetricType.FPS, true);
captureList.Add(MetricType.GPU, true);
captureList.Add(MetricType.BAT, false);
captureList.Add(MetricType.POW, false);
captureList.Add(MetricType.MEM, false);
GBStatus state = sdk.StartPerformanceCapture(captureList);
Start session, capture all metrics:
Gamebench.Sdk.IGamebenchSDKLifeCycle sdk = Gamebench.Sdk.GamebenchSDKLifeCycle.GetInstance();
GBStatus state = sdk.StartPerformanceCapture();
Configure GPU and Memory capture frequency (if not set, the default capture frequency will be used)
Gamebench.Sdk.IGamebenchSDKLifeCycle sdk = Gamebench.Sdk.GamebenchSDKLifeCycle.GetInstance();
sdk.InitSDK();
var frequencyList = new Dictionary<MetricType, float>();
frequencyList.Add(MetricType.GPU, 2f);
frequencyList.Add(MetricType.MEM, 3f);
sdk.ConfigCaptureFrequency(frequencyList);

Tags

Add tags to sessions recorded using the SDK by modifying Assets/Resources/GameBenchSDK/SDKConfig.txt. Tags should be key=value. Comma separate multiple tags. For example:

{
    ...
    "tags": "foo=bar,baz=bat"
    ...
}

SDK overhead

GameBench SDK has minor overhead and you can expect the following values:

Architecture CPU Memory
Android ARMv7 1% 4 Mb
Android ARM64 1% 4 Mb
iOS ARM64 0.1% 3 Mb

Storage and upload size overhead - 10Kb for 10 mins session

Power overhead

The overhead of the GameBench SDK is approximately 4mA when enabled. We have conducted these tests on an iPhone 11 and a Galaxy S20 Ultra device. The observed power overhead is minimal when the SDK is enabled. (For comparison, enabling Instruments in Apple takes up an additional power drain of 40 - 50 mA.)

iPhone 11

Content (3 minutes) Without SDK (mA) With SDK (mA)
Power Drain (Run1) 208 207.5
Power Drain (Run2) 205 206.7
Power Drain (Run3) 198 202
Power Drain (Avg) 203 205.4

Average overhead -> 2-3 mA

Galaxy S20 Ultra (Snapdragon)

Content (3 minutes) Without SDK (mA) With SDK (mA)
Power Drain (Run1) 452 455
Power Drain (Run2) 457 461
Power Drain (Run3) 459 458
Power Drain (Avg) 456 458

Average overhead -> 2-3 mA

Known issues

Unable to archive product in Xcode 11.2.1

If you encounter linking errors similar to:

ld: could not reparse object file in bitcode bundle: 'Invalid bitcode version (Producer: '1103.0.32.59.0_0' Reader: '1100.0.33.12_0')', using libLTO version 'LLVM version 11.0.0, (clang-1100.0.33.12)' for architecture arm64
clang: error: linker command failed with exit code 1 (use -v to see invocation)

Please try upgrading to Xcode 11.4.1

Troubleshooting

When building for Android, if you encounter the following error:

SDK Android API error

Please set the “Minimum API level” in the player settings to at least 21.

Uninstallation

To uninstall the Gamebench SDK you will need to remove from the filesystem:

  • Assets/GamebenchSDK/*
  • Assets/Plugins/Android/communicatelibrary-debug.aar
  • Assets/Plugins/Android/libs/arm64-v8a/libgbsdk.so
  • Assets/Plugins/Android/libs/armeabi-v7a/libgbsdk.so
  • Assets/Plugins/iOS/libcore.a
  • Assets/Plugins/iOS/libgbproto.a
  • Assets/Plugins/iOS/libgbsdk.a
  • Assets/Plugins/iOS/libmetalib.a
  • Assets/Plugins/iOS/libprotobuf.a
  • Assets/Plugins/iOS/libsession.a
  • Assets/Resources/GamebenchSDK/*