geordi-client

A JavaScript client for the Geordi user analytics capture engine.

This library simplifies the process of posting an event to Geordi.

It will also log the event to Google Analytics. Google Analytics is useful for analysing the events in bulk. Geordi's database is more useful for tracking individual records. As such if Google Analytics' Google Tag Manager javascript isn't loaded into your application, you will get a warning each time you log with this client.

To use the Geordi client in your project, first type:

npm install --save zooniverse-geordi-client

This will save the geordi library dependency into your project.

Now, in your app/geordi-client.coffee file (for hem projects), or your first-loaded JavaScript file otherwise, load and configure Geordi. This example is in CoffeeScript:

# import any needed modules
Subject = require 'models/subject'
User = require 'zooniverse/lib/models/user'

# load the geordi client class
GeordiClient = require 'zooniverse-geordi-client'

# define callback functions that you will pass to Geordi to allow retrieval of current user ID or subject ID
checkZooUserID = ->
  User.current?.zooniverse_id

checkZooSubject = ->
  Subject.current?.zooniverseId

# instantiate the Geordi client into a variable
Geordi = new GeordiClient({
  "server": "staging"
  "projectToken": "serengeti"
  "zooUserIDGetter": checkZooUserID
  "zooUserIDGetterParameter": null # this line can be omitted if no parameter is required
  "subjectGetter": checkZooSubject
  "subjectGetterParameter": null # this line can be omitted if no parameter is required
})

If necessary, this can be added into a setup file, as shown in Snapshot Serengeti here. This linked example also shows how to initialize Geordi when using an experiment server such as the Zooniverse Experiment Server as well.

Once Geordi is loaded into your JavaScript namespace, you can log an event very simply to Geordi as follows in this one-line CoffeeScript example:

Geordi.logEvent 'classify'

This would log an event of type "classify".

The projectToken will be set as specified in your configuration, the userID and subjectID will be automatically retrieved using your provided zooUserIDGetter and subjectGetter respectively, passing the zooUserIDGetterParameter and subjectGetterParameter respectively, if specified, and the serverURL, clientIP, userAgent and browserTime will be set automatically by the server, as well as userSeq, sessionNumber, and eventNumber.

Alternatively, you can pass a parameter object instead of a string, to set multiple parameters at once:

Geordi.logEvent {
  'type': 'classify'
  'relatedID': '123-456'
  'subjectID': 'ASG00312'
}

This will log an event of type "classify" with a relatedID of "123-456" and a subjectID of "ASG00312"

The zooniverse-user-string-getter library will be used to obtain the user ID string to pass to Geordi.

You can also use this method to log web application or other errors to Geordi, as in this CoffeeScript example:

Geordi.logEvent {
  'type': 'error'
  'subjectID': 'ASG00312'
  'errorCode': '409'
  'errorDescription': 'Couldn't load subject'
}

Note, you do not have to use type "error" for errors.

The list of parameters supported by logEvent is: userID, subjectID, relatedID, errorCode, errorDescription, projectToken, serverURL, experiment, cohort, type, browserTime and data. These are all required to be non-zero length strings, except for data which must be an object, and browserTime which should be a Javascript date in number format, corresponding to a date and time no earlier than midnight, September 1st, 2015. The only required field is type. If type is omitted, it will be set to "error".

A note on Experimental Server integration

Geordi and the Geordi Client are also designed to integrate with the Zooniverse Experiment Server. This not currently documented as the Experimental Server client code is about to undergo a major refactoring. Refer to the Snapshot Serengeti codebase here to see how this can work, or talk to Alex Bowyer for more information.

References

Please refer to the Geordi documentation for more information on logging events to Geordi and the work this client does for you.