GameBench Documentation
Studio SDK
Integration Guides
Post-build

Integrating post-build

Integrating post-build means the GameBench native library gets added to your app bundle (your .apk or .ipa) after it has been built. This may be desirable if you want to set up a special build pipeline for performance testing without having to modify your project source code.

To achieve this we provide a Java-based command-line tool named gbtool which takes your app bundle as input and which outputs the same app bundle but with the GameBench library inside it.

The output app bundle should be signed with the same signing assets used to create the input app bundle. You will pass these assets as options to gbtool.

Steps

1. Download the GameBench SDK

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

  • lib/GameBench.aar. The native library for Android
  • lib/GameBench.framework. The native library for iOS
  • tools/gbtool.jar. The command line tool needed for post-build integration.
Do not copy or move these files after unzipping - gbtool.jar will expect to find the native libraries at ../lib relative to its own location.

2. Create a configuration file

Since this integration method doesn’t involve code, GameBench must be configured with a JSON config file. At a minimum this file should include your server url and credentials.

Below is an example JSON config file showing hypothetical credentials and a reasonable set of metric collection intervals. Refer to Configuration for full details.

{
    "url": "https://web.gamebench.net/",
    "user": "you@yourcompany.com",
    "token": "0123456789abcdef0123456789abcdef",
    "metrics": {
        "CPU": 1.0,
        "GPU": 1.0,
        "MEM": 1.0,
        "MEM": 1.0,
        "NET": 1.0,
        "POW": 5.0,
    }
}

3. Obtain the input app(s)

This bit is obviously up to you and your company’s way of working. Let’s assume your build produces both Android and iOS app bundles called mygame.apk and mygame.ipa.

4. Run gbtool

Assuming you have a JDK installed, run gbtool.jar passing it an input app bundle and your json config file. Codesigning args should follow a ‘–’ separator, they will be passed verbatim to the appropriate platform code signing tool. For Android this tool is called apksigner (link) and it usually requires a path to a keystore file and a password. For iOS you must pass the SHA-1 of an installed signing certificate as well as the path to the provisioning profile:

Android
java -jar tools/gbtool.jar mygame.apk gbconfig.json -- --ks MyKeystore.jks --ks-pass pass:MyPassword

iOS
java -jar tools/gbtool.jar mygame.ipa gbconfig.json -- "89E558C4772B9BADD76782C20EFA9A11517CCD73" -p my_ios_dev.mobileprovision

iOS: You must be on MacOS and have up-to-date XCode Command line tools installed.

GBTool will output an app bundle with the same filename with -gb appended, e.g. mygame-gb.apk.

5. Deploy output app to a device

For Android you can use adb install mygame.apk, for iOS you can use ideviceinstaller -i mygame-gb.ipa (which is part of libimobiledevice).

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 the url in your config file, and ensure you are logged in with the same credentials. Switch to the “Sessions” tab and your session should be visible.

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

Last updated on
Native (Java/Android)