Skip to main content

SDK Features

Debug & Event Verification​

Debug​

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 the Xcode console. We have 2 different debug log types that can be enabled / disabled independently:

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

tip

Enable info log when implementing the SDK – remember to turn it off in production!

// Objective-C
[GameAnalytics setEnabledInfoLog:YES];
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.

// Objective-C
[GameAnalytics setEnabledVerboseLog:YES];

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.

// Objective-C
// enable verbose log
[GameAnalytics setEnabledVerboseLog:YES];
// add event you need to troubleshoot / inspect
[GameAnalytics addDesignEventWithEventId:@"Some:Event" value:@100];
// disable verbose log
[GameAnalytics setEnabledVerboseLog:NO];

Verification​

You can enable the Info Log to verify that events are being sent from your game project without any issues being reported. Events submitted should register after a minor delay in our realtime dashboard in the GameAnalytics dashboard.

tip

Read more about the realtime dashboard and our data processing.

Session Handling​

By default the SDK will handle session start/end automatically, but it is also possible to manually control this yourself.

Be aware that the initialization will always automatically start the first session even with manual session handling.

Automatic session handling​

The automatic session handling will track the focused time the user is spending in your game – from game launch to the user leaving the game.

session start

On iOS a new session will start once the SDK is initialized or when the game is going to foreground.

session end

A session will end once the game is going to background.

Manual session handling​

You can enable/disable manual session handling if you wish to control when sessions end/start.

// Objective-C
[GameAnalytics setEnabledManualSessionHandling:YES];
caution

You will then need to call endSession and startSession at the appropriate times.

With manual session handling it is recommended to also call endSession when the game goes into the background. This will ensure a correct session ending when users click the home or on/off button.

startSession()

This will start a new session if the manual session handling is enabled. If a current session is active then it will end the current session and start a new one.

// Objective-C
[GameAnalytics startSession];

endSession()

This will end a session if the manual session handling is enabled or if a session is already active (initialize will start a session automatically)

// Objective-C
[GameAnalytics endSession];

Behind the scenes​

This is what happens when the session is starting or ending.

Session start​

  1. Generates a new session.
  2. Adds a session start event (an “user” event).
  3. Start the periodic activation of submitting queued events. Next event submit will fix potential missing session_end from earlier sessions.

Session end​

  1. Stop the periodic activation of submitting queued events.
  2. Add a session_end event.
  3. Submit queued events.
info

If you are deploying testflight builds then please note that user id’s are handled a bit differently.

The testflight environment is lacking any useful identifiers (they are random each app launch). The SDK will create a random user_id internally and use it for each app launch. If the game is removed and installed again, then a new user_id will be created though and it will register as a new user. Once it is deployed to the app store (or run locally on an actual device) it will track users (returning etc.) correctly.

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.

Offline Queue​

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

Thread Handling​

For the iOS platform almost every piece of the SDK code is run using a dedicated low-priority serial thread queue to avoid UI lag or sudden performance spikes.

dispatch_queue_create("gameAnalyticsQueue", DISPATCH_QUEUE_SERIAL);

The queue will execute each task sequentially. If the SDK adds several tasks to the queue then each will have to wait until its turn. A task could be adding an event or submitting queued events. Consider this example with 3 calls.

// Objective-C
// Configure build version
[GameAnalytics configureBuild:@"alpha 0.1.0"];
// Initialize
[GameAnalytics initializeWithGameKey:@"12341234123412341234123412341234" gameSecret:@"1234123412341234123412341234123412341234"];
// Add Design event
[GameAnalytics addDesignEventWithEventId:@"Some:Event"];

The configureBuild method is required to be called before initialize is completely finished. The design event call is required to be submitted after initialize is finished. The queue will ensure all tasks have been completed in the order they have been called.