SDK User Guide

Latest Version: 0.5.1
Status: This version should not be included into release or release candidate games. v0.5 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. 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)

Supported Unity versions

  • Unity 2017/18/19
  • 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.
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.

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

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

Known issues

Unity 2020

Unity 2020 is not currently supported. We support Unity versions 2017, 2018 and 2019. We will add support for 2020 in v0.6.0.

Session upload

In some cases, a session upload might not be triggered when the App is backgrounded. These are uploaded when the app is launched in the foregound.

Crashes

The SDK will not upload a session if a game crashes during capture time. We will improve crash handling in v0.6.0.

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/*