SDK User Guide

Latest Version: 0.3
Status: This version should not be included into release or release candidate games. v0.3 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
  4. SDK Overhead
  5. 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 4.2 or above (armeabi-v7a and ARM64)

Supported Unity versions

  • Unity 2017/18/19
  • Unity Scripting Backend: IL2CPP and Mono

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” - 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.
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

FPS

All sessions captured by 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.

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);
     * */
}

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

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