SDK features

Debugging

The SDK is designed to be as silent as possible and use very few resources. You will therefore not get much information by default in your development console.

We have 2 different debug log types that can be enabled / disabled (at any time):

• info log
• verbose log

Info log

Short messages will be output when enabled explaining when some action is being performed by the SDK. Sometimes cropping text / values to make it more readable. Enable info log when implementing the SDK – remember to turn it off in production!

gameanalytics::GameAnalytics::setEnabledInfoLog(true);

Info/GameAnalytics: Add DESIGN event: {eventId:someEvent, value:0}
Info/GameAnalytics: Add DESIGN event: {eventId:someOtherEvent, value:100}
Info/GameAnalytics: Add ERROR event: {severity:info, message:This is some in}

Verbose Log

Console output when each event is added (all fields) in JSON string format. This is the data being submitted to the GA servers for each event.

Enable verbose log when troubleshooting events:

gameanalytics::GameAnalytics::setEnabledVerboseLog(true);

This can result in a lot of text. When troubleshooting/debugging events it is therefore recommended to enable/disable when performing the action that need inspection.

Troubleshooting example:

// enable verbose log
gameanalytics::GameAnalytics::setEnabledVerboseLog(true);
// add event you need to troubleshoot / inspect
gameanalytics::GameAnalytics::addDesignEvent("Some:Event", 100);
// disable verbose log
gameanalytics::GameAnalytics::setEnabledVerboseLog(false);

Log file save location

By default the log files are saved in the following location:

• Windows: %LOCALAPPDATA%/GameAnalytics
• Mac OSX: ~/GameAnalytics

If you wish to save the log files in a custom location you can do so by calling the following function:

GameAnalytics::configureWritablePath(const std::string& writablePath):

Custom Dimensions

GameAnalytics supports the use of up to 3 custom dimensions:

• Custom01
• Custom02
• Custom03

During the game it is possible to set the active value for each custom dimension dynamically. Once a dimension is set it will be persisted across sessions/game-start and automatically be added to all event categories.

Remember you have to set the custom dimensions before initialzing the SDK (but after setting the available custom dimensions) to be able to add the dimensions to the first session start event.

During gameplay it is possible to set values for 3 different custom dimensions. For each custom dimension it is needed specify a whitelist.

caution

You cannot set a custom dimension value unless it is specified here first.

gameanalytics::GameAnalytics::setCustomDimension01("ninja");
gameanalytics::GameAnalytics::setCustomDimension02("dolphin");
gameanalytics::GameAnalytics::setCustomDimension03("horde");

gameanalytics::GameAnalytics::setCustomDimension03(""); // reset custom dimension 3

tip

Read more about custom dimensions here.

Field	Type	Description	Example
customDimension	string	One of the available dimension values set in the configuration phase. Will persist cross session. Set to empty string to reset.	"ninja"

Custom Event Fields

caution

Custom event fields will not be available in the GameAnalytics web-tool.

tip

Read more about how to use Custom Event Fields here.

Custom event fields are a collection of key-value pairs that can be added to any event during gameplay. These global custom event fields can be updated at any time.

You can also override the global custom event fields by using the optional custom event fields parameter when sending individual events. For more information on how to use this feature, please refer to the events documentation page.

To set global custom event fields, follow these steps:

constexpr const char* fields = "{\"test\": 1000, \"tests\": \"hello_world\"}";
gameanalytics::GameAnalytics::setGlobalCustomEventFields(fields);

Field	Type	Description	Example
customFields	dictionary	A set of key-value pairs. Values can be strings or numbers	{   "test": 1000,   "tests": "hello_world" }

Session Handling

Sessions are the concept of a user spending focused time in your game – from game launch to the user leaving the game.

On UWP a new session will start once the game is launched (or when the app is “resuming”). A session will end once the game is suspended.

On Windows, Linux and Mac, gameanalytics::GameAnalytics.onStop() should be called manually before quiting the game to create an end session event.

Session start

Generate new session and adds a session start event (a “user” event). Starts the periodic activation of submitting queued events.

info

Next event submit will fix potential missing session_end from earlier sessions.

Session end

Stop the periodic activation of submitting queued events. Adds a session_end event. Submit queued events. Should be called when the application is closed.

To ensure the background thread of the SDK will not continue running after the application has closed you need to call:

gameanalytics::GameAnalytics::onQuit();

Event Queue

Whenever an event is added (and validated) it will be added to a local database queue.

Every 8 seconds the SDK will start a task for submitting queued events since last submit. This processing is done in a separate low-priority thread that will have minimum impact on performance. The payload is gzipped and will therefore only consume a small amount of bandwidth.

When a device is offline the events are still added to the queue. When the device comes back online it will submit the cached events.

Thread Handling

Almost every piece of this code is run using a dedicated low-priority serial thread queue to avoid UI lag or sudden performance spikes. The queue will execute each task sequentially.

If the SDK adds several tasks to the queue then each will be executed in order. A task can be adding an event or submitting all queued events.

Consider this example with 3 calls:

// Configure build version
gameanalytics::GameAnalytics::configureBuild("alpha 0.1.0");
// Initialize
gameanalytics::GameAnalytics::initialize("12341234123412341234123412341234", "1234123412341234123412341234123412341234");
// Add Design event
gameanalytics::GameAnalytics::addDesignEvent("Some:Event");

The configureBuild is required to be called before initialize is completely finished. The design event call is required after initialize is finished. The queuing will make sure that each task is completely finished before proceeding to the next one.