Skip to main content

SDK Features

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 or during configuration).

  • 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.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.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.setEnabledVerboseLog(true)
-- add event you need to troubleshoot / inspect
gameanalytics.addDesignEvent {
eventId = "Some:Event",
value = 100
}
-- disable verbose log
gameanalytics.setEnabledVerboseLog(false)

Session Handling

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

danger

Be aware that the initialization will always automatically start the first session even with manual session handling. If you are using ads in your game there is a big possibility that the onPause() and onStop() events will be triggered when the ads are showing which will interfere with the session length

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.

On Android a new session will start once the game is launched or when the app is resumingif there is no current session.

A session will end once the game is going to homescreen (or is not visible anymore).

It will end the session at once if the application received the onStop event from the game activity. It can also end the session if onPause event was received and 90 seconds have passed (sometimes only the onPause will trigger even though the user left the app). Manual session handling

The automatic session handling only works if the game is contained in one activity.

It will then handle session end and start based on the events on that single activity. This behavior is common (having one activity) but some games define multiple activities and this automatic session handling will not work in an optimal way.

If your game does have multiple activities (or you just want to be in control when to start and end sessions) you can enable/disable manual session handling by calling this at any given time:

gameanalytics.setEnabledManualSessionHandling(true)
info

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

info

With manual session handling it is recommended to also call endSession when the game activity event onStop is fired. This will ensure a correct session close when users click the home or on/off button.

If a current session is active then it will end the current session and start a new one. Handling ads and preserve correct session length

Ads will most likely trigger onPause() and onStop() which will interfere with the session length of the game. To prevent this you need to use manual session handling at least when you are about to show ads.

If you are already using manual session handling from the beginning of your game then you don’t need to worry about this.

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

Session start

  • Generate new session.
  • Add a session start event (a “user” event).
  • Start the periodic activation of submitting queued events.
  • Next event submit will fix potential missing session_end from earlier sessions.
gameanalytics.startSession()

This will start a new session if:

  • manual session handling is enabled
  • SDK is initialized (initialize will start a session automatically)

Session end

  • Stop the periodic activation of submitting queued events.
  • Add a session_end event.
  • Submit queued events.
gameanalytics.endSession()

This will end a session if:

  • manual session handling is enabled
  • a session is active
  • SDK is initialized (initialize will start a session automatically)

Event Queue

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

Interval

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.

info

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

Thread Handling

For the Android platform 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 add several tasks to the queue then each will be executed in turn. A task could be adding an event or submitting all queued events.

Consider this example with 3 calls.

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

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