Skip to content

Latest commit

 

History

History
254 lines (177 loc) · 9.68 KB

README.md

File metadata and controls

254 lines (177 loc) · 9.68 KB
Raw

GA-JavaScript-SDK Build Status

GA-JavaScript-SDK is an open-source javascript implementation for GameAnalytics and their new, improved v2 REST API.

This library is fully compliant with the data structures specified in GameAnalytics' REST API docs

If you don't feel like reading any further, or you like to see how it works, then check out the example in the repo!

Getting Started

If you don't have an account yet GameAnalytics then hurry up and create one, it's for free!

Set up a game, and make sure you've received a game key and a private key, we need those to talk to GameAnalytics' API.

Once that's out of your way, snatch yourself a copy of this library either from the repo or catch the latest stable from the releases.

Include in your project like you usually do:

<script src="/path/to/GaJavascriptSdk.min.js" />

And initialise the library, this requires the previously obtained game and secret key, a build string that specifies the current state of your game and a User object.

var gameKey = "a50a4caeda2e82fd1bedc5aca519ed12"; //Your gamekey
var secretKey = "790518ec21b665def89412852862081649cf2a9c"; //Your secret key
var build = "1.0"; //The current version of your game, it's wise to bump this with every analytics/game change

//here's the user, it needs some things to start off
//First up is the unique id that specifies the current user
//Then (if applicable) you can send a facebook userid, this overwrites the previous set user_id
//Third is the gender of the user, for now GameAnalytics only accepts Male|Female
//And last is user's birth year, all for those awesome stats!
var user = new GA.User(Date.now().toString(), undefined, GA.Gender.male, 1970);

Usually you're backend/platform keeps track of this data, but if you don't then just create an empty user object. The library will create an userId for you, and make sure the session number is correctly updated

Now let's instanciate this thingy:

//Create an instance, initialise it!
//Here we use all those things we defined before, now everything should be set up correctly!
var gaan = GA.getInstance();
gaan.init(gameKey, secretKey, build, user)

After setting everything up correctly you should be able to see Events comming in on the live-feed at your game in GameAnalytics.

Not seeing events appearing? Check our troubleshooting guide

Processing Queue

Events normally are added trough the addEvent method

GA.getInstance().addEvent(event);

Added events are not immediately send to GameAnalytics, instead they are added to an internal queue that is drained every 15 seconds. Multiple events are grouped and then send as a single request. This way there is less connections made to the GameAnalytics servers, and this keeps them happy.

It is possible to drain the queue yourself, by using the sendData() method.

GA.getInstance().sendData();

Events

These are the different kind of Events that can be send to GameAnalytics. They're all available under GA.Events, but all have different arguments that are required for succesfull sending of events.

Please note that the documentation on the event_id's is not complete. For a full documentation on this, please refer to GameAnalytics' REST API documentation

User

The user event acts like a session start. It should always be the first event in the first batch sent to the collectors and added each time a session starts.

var event = new GA.Events.User();

GA.getInstance().addEvent(event);

Progression

Progression events are used to track attempts at completing levels in order to progress in a game. During the progression attempt all other events activated in that period should be annotated with the progression values. This will enable dimension filtering in the GameAnalytics tool for each progression type. There are 3 types of progression events.

  • Start
  • Fail
  • Complete
var progressStart = new GA.Events.Progression(
    'Start:Shopping'  //A 2-4 part event id.
);

var progressFail = new GA.Events.Progression(
    'Fail:Shopping', //A 2-4 part event id.
    1,               //The number of attempts for this level. Add only when Status is “Complete” or “Fail”. Increment each time a progression attempt failed for this specific level.
    200              //(optional) An optional player score for attempt. Only sent when Status is “Fail” or “Complete”
);

var progressComplete = new GA.Events.Progression(
    'Complete:Shopping', //A 2-4 part event id.
    5,                   //The number of attempts for this level. Add only when Status is “Complete” or “Fail”. Increment each time a progression attempt failed for this specific level.
    1337                 //(optional) An optional player score for attempt. Only sent when Status is “Fail” or “Complete”
);

GA.getInstance()
    .addEvent(progressStart)
    .addEvent(progressFail)
    .addEvent(progressComplete);

Business

Business events are for real-money purchases.

var event = new GA.Events.Business(
    'GemPack1:Gems1000',    //A 2 part event id
    100,                    //The amount in cents
    'EUR',                  //The currency
    11,                     //Store this value locally and increment each time a business event is submitted during the lifetime (installation) of the game/app.
    'level_end_shop'        //(optional) A string representing the cart (the location) from which the purchase was made.
);

GA.getInstance().addEvent(event);

Resource

Resource events are for tracking the flow of virtual currency registering the amounts users are spending (sink) and receiving (source) for a specified virtual currency. There are 2 types of Resource events:

  • Sink
  • Source

Sink is when a user spends some currency and Source is when he gains some

var sink = new GA.Events.Resource(
    'Sink:Lives:continuity:startLevel', //A 4 part event id string. [flowType]:[virtualCurrency]:[itemType]:[itemId]
    1                                   //The amount
);

var source = new GA.Events.Resource(
    'Source:Gems:purchase:gemPack1337', //A 4 part event id string. [flowType]:[virtualCurrency]:[itemType]:[itemId]
    1337                                //The amount
);

GA.getInstance()
    .addEvent(sink)
    .addEvent(source);

Design

Every game is unique! Therefore it varies what information is needed to track for each game. Some needed events might not be covered by our other event types and the design event is available for creating a custom metric using an event id hierarchy.

var event = new GA.Events.Design(
    'Character:Poop',   //A 1-5 part event id.
    10                  //(optional) a number
);

GA.getInstance().addEvent(event);

SessionEnd

Whenever a session is determined to be over the code should always attempt to add a session end event and submit all pending events immediately.

Only one session end event per session should be activated.

var sessionDuration = (Date.now() - sessionStart) / 1000;

var event = new GA.Events.SessionEnd(
    sessionDuration //the length of the session in seconds
);

GA.getInstance().addEvent(event);

Exception

An Error event should be sent whenever something horrible has happened in your code - some Exception/state that is not intended.

the following error types are supported.

  • GA.Events.ErrorSeverity.debug
  • GA.Events.ErrorSeverity.info
  • GA.Events.ErrorSeverity.warning
  • GA.Events.ErrorSeverity.error
  • GA.Events.ErrorSeverity.critical
window.addEventListener('error', function (event) {
    var stack = event.message;

    if (event.hasOwnProperty('error') && event.error.hasOwnProperty('stack')) {
        stack = event.error.stack;
    }

    var event = new GA.Events.Exception(GA.Events.ErrorSeverity.critical, stack);

    GA.getInstance().addEvent(event);
});

Troubleshooting

I don't see any events in the live-feed

First of all, make sure your keys are correctly set up. Also note that the events are queued and drained every 15s, so it might take some time in the beginning before any events are set.

The library also sends an Init event to GameAnalytics, this is to check if a user is allowed to send events, if the user isn't then events won't be send so we don't hammer GameAnalytics unnecessary.

Still having trouble? Submit an issue

Changelog

2.1.0

  • Changed the way userId's are handled and made sure session_num is used

2.0.4

  • Fixed a typo in the SessionEnd event that gave wrong session times

2.0.3

  • Changed os version to use regexp so all version numbers are included

2.0.2

  • Fixed an issue where the wrong OS versions are send
  • Made sure http/https is used
  • Updated README

2.0.1

  • Fixed os/os_version
  • Created enum for different os' support by GA
  • Removed sandbox url / keys
  • Updated example
  • Added correction for server time difference

2.0.0

  • Reworked everything to work with GameAnalytics v2 API]

Disclaimer

We are in no way affiliated with GameAnalytics. We just like making HTML5 games and we needed some analytics in our games, hence this library was born.