Analytics

This module exposes an abstraction to standardize how games report events, page views and errors to our supported analytics systems.

Using the analytics feature is a 2 steps process:

• the game is expected to pass analytics provider configuration to the relevant analytics systems
• the game is to report back a set of standard events and page views, as soon as they happen.

Supported Providers

Game SDK can be hooked up to the following providers:

• App Insights - this provider has tight integration with Arkadium's Game SDK;
• Console - this provider's sole purpose is debugging. Instead of reporting to a system, it logs what is to be sent to the browser's console. Useful to set up at early stages of development and on tweaking tasks for analytics reporting.

caution

Avoid keeping the Console Provider active on a commit meant for release.

Concepts

A page view is notifying the system about the player having reached a certain key screen of the game.
Examples of these would be the intro, game and game over screens.

An event is something that took place and is relevant to the game journey.
Examples of these would be first move, round, round end, settings changes.

Both page views and events will send along them a set of relevant dimensions that help understand the player, game and device behavior.
Common dimensions are score, time spent and device type.

Besides page views and events, analytics can also catch game errors.

Setup

At game bootstrap, be sure to call game sdk's configure provider once for each provider you need to integrate against.

await sdk.analytics.configureProvider({
    provider: sdk.analytics.CONSOLE,
    appId: 'test',
});

await sdk.analytics.configureProvider({
    provider: sdk.analytics.APP_INSIGHTS,
    appId: '08a82ae3-afc0-4532-b61e-c76be7277faa',
});

caution

Every game should be assigned an appId for App Insights. Ask these from your Arkadium liaison if you don't yet have these.

Populating dimensions

caution

When using App Insights, there are some limits regarding the Dimensions sent on events:

• Maximum key length: 150
• Maximum value length: 8,192

Every dimension that exceeds these limits will be truncated when sent through App Insights.

Please refer to this documentation for further info.

The dimensions object passed to analytics APIs is an object of key/value pairs.

You can set dimensions to be used in all events by calling the setDimensions API:

sdk.analytics.setDimensions({
    gameVersion: '0.1.1',
    domain: 'bogus.com',
});

Whenever you trigger a page view or event, you can update dimensions too:

sdk.analytics.sendRoundEndEvent('Finished', { reason: 'No_Moves' });

sdk.analytics.sendGameOverPageView({ score: 1234 });

tip

If you're using TypeScript, you can get hold of the Dimensions enum so you avoid typos passing dimension names.

Reporting events

There's a set of standard events which have helper methods to ease calling them. All games are expected to call the subset of these events that makes sense for the game genre (ie, first right answer and first match event make sense only in trivia/word games and match threes and puzzles games, while gameplay ready is useful for all games).

// Custom event
sdk.analytics.sendEvent(eventCategory: string, eventAction: string, dimensions: DimensionsObject)

// Standard events
sdk.analytics.sendMenuActionsEvent('Sound_On');
sdk.analytics.sendStartButtonClickedEvent('New', { timespent: 123 });

// Start of the Game
sdk.analytics.sendAppStartedEvent() 

// Loading ended, user can see Start button (after preroll ends)
sdk.analytics.sendMainScreenReadyEvent()

// User clicked on Start Button [action 'Loaded' if user continued previous game, otherwise New]
sdk.analytics.sendStartButtonClickedEvent(action: 'New' | 'Loaded')

// User sees gameplay and can interact with it
sdk.analytics.sendGameplayReadyEvent()

// User made first move (any click on the page)
sdk.analytics.sendFirstMoveEvent()

// User entered the first right answer (for word games or trivia games and other applicable games)
sdk.analytics.sendFirstRightAnswerEvent()

// User made first match (for match-3, mahjongg and other applicable games)
sdk.analytics.sendFirstMatchEvent()

// User made first shot (for shooters and other applicable games)
sdk.analytics.sendFirstShotEvent()

// User started new Round (Level). First round is Round 1 (not 0)
sdk.analytics.sendRoundEvent({ round: 1})

// User ends a round
// action:
// - Finished - User successfully finished the Round (Level).
// - Not_Finished - User didn't finish the Round (Level) successfully OR leaves the game OR skips the round OR Quit
// dimensions:
// - round - The round that ended. First round is Round 1 (not 0)
// - reason - The reason for the round to end, either 'No_Moves' or 'Time_Out'
// sdk.analytics.sendRoundEndEvent(action: 'Finished' | 'Not_Finished', dimensions: { round: number, reason: 'No_Moves' | 'Time_Out' })
sdk.analytics.sendRoundEndEvent('Finished', { round: 1, reason: 'No_Moves' }) // round 1 finished due to no more moves being available

// Game ends
// action:
// - Win - The game ended because the user won
// - Lose - The game ended because the user lost or faces "No More Moves' situation
// - Time_Out - User ended game because he runs out of time
// - New_Game - User ends game because he starts a new game: click on 'New Game', then click on 'Yes'
// - Quit - User ends game because he quits a new game: click on 'Quit', then click on 'Yes'
// - Restart - User starts the same game from the beginning again (mostly for Solitaire games): click on 'Restart', then click on 'Yes'
// sdk.analytics.sendGameEndEvent(action: 'Win' | 'Lose' | 'Time_Out' | 'New_Game' | 'Quit' | 'Restart')
sdk.analytics.sendGameEndEvent('Win') // user won the game

// User clicked on Reshuffle (for mahjonggs and other applicable games)
sdk.analytics.sendReshuffleEvent()

// An error occurred
// sdk.analytics.sendErrorEvent(dimensions: { reason: string })
sdk.analytics.sendErrorEvent({ reason: 'An error occurred' })

// User turned sound on/off or music on/off
// sdk.analytics.sendMenuActionsEvent(action: 'Sound_On' | 'Sound_Off' | 'Music_On' | 'Music_Off')
sdk.analytics.sendMenuActionsEvent('Sound_On'); // user turned sound on

// Clicks on Help button on Game_Screen or in the menu
sdk.analytics.sendHelpEvent()

// Impression of FUE - tutorial [aplicable for multiple stages tutorial which appear in different places]
// sendFUEEvent(dimensions: { action: string })
sdk.analytics.sendFUEEvent({ action: 'tutorial_step_1'})

Reporting page views

Page views are expected to be reported less frequently than events, as games don't change screen often.
These are the page views we support for all games:

// Custom page view
sdk.analytics.sendPageView(pageName: string, dimensions: DimensionsObject);

// Standard page views
sdk.analytics.sendIntroScreenPageView(); // First screen
sdk.analytics.sendGameScreenPageView(); // Next page after user clicks on Start
sdk.analytics.sendGameOverPageView({ score: 1234, timespent: 420 }); // Game over page == every game end, except Quit
sdk.analytics.sendQuitConfirmedPageView(); // When player manually quits the game

Reporting errors

Sometimes a game errors in unexpected locations. Games should be robust and handle those, but there is value in capturing errors. Capturing errors is not mandatory and on release builds where the game code is hardened it may be challenging to track the lines/functions. You still have it at your disposal.

try {
    throw new Error('test');
} catch (error) {
    sdk.analytics.trackException(error);
}