NODEJS = module?.exports?
Keep track of what environment we're running in, Node.js or a browser.
NODEJS = module?.exports?
If we're in Node, require the https
module for our network requests.
If we're in a browser we'll just use the implicit requests generated by
Image().src
. Kissmetrics responds to API requests with an image/gif
content type, so the browser won't throw up any warnings.
https = require 'https' if NODEJS is on
Wrapper for interacting with the Kissmetrics API.
Instantiates a new client with your Kissmetrics API key and an identifier for the person you're recording data about. A new client must be created for each person you record data about.
All data methods (record
, set
, alias
) are chainable.
km = new KissmetricsClient(API_KEY, user);
km.record('Changed username')
.alias(user.newname)
.set({mood: 'indecisive'});
apiKey
(String): Your API key from Kissmetrics
person
(String): An identifier for the person you'll record data about
options
Optional (Object):
queue
: Indicates you want to batch queries. Must be an object with
an add()
method. All queries recorded on instances that defined this
option will be added to the queue and not sent immediately. This
option is only supported on the server. Currently the apiKey
argument is ignored when requests are batched because an API key is
specified in the batch request headers.km = new KissmetricsClient(API_KEY, 'evan@example.com')
class KissmetricsClient
@HOST: 'trk.kissmetrics.com'
@QUERY_TYPES:
record : 'e'
set : 's'
alias : 'a'
constructor: (@apiKey, @person, options = {}) ->
@queries = []
if NODEJS is on and options.queue
BatchClient = require './kissmetrics-batch'
@batchClient = new BatchClient options.queue
Syntactic helper to access process batch events without specifically
loading the batch module specifically. Refer to the
Batch Kissmetrics documentation for
BatchKissmetricsClient.process()
to see what the
method actually does.
Like the rest of the BatchKissmetricsClient
class, this method is
only accessible in Node.js, not in the browser.
@batchProcess: (batchProcessArgs...) ->
return unless NODEJS is on
require('./kissmetrics-batch').process batchProcessArgs...
Record an "event" in Kissmetrics.
http://support.kissmetrics.com/apis/common-methods#record
action
(String): Name of the event you're recording. This is
usually something a person did or something that affects them.
properties
Optional (Object): Properties to associate with
the person's event. Keys will be used as property names and values
as property values.
km.record('Signed up', {page: 'home'})
record: (action, properties = {}) ->
properties._n = action
@_generateQuery 'record', properties
Set a "property" in Kissmetrics.
http://support.kissmetrics.com/apis/common-methods#set
properties
(Object): Properties to associate with the person. Keys
will be used as property names and values as property values.
This behaves exactly like the properties
argument in record
, except
it includes an additional safety check to make sure you don't use the
reserved _n
property name.
km.set({location: 'San Francisco', gender: 'male'})
set: (properties) ->
delete properties._n
@_generateQuery 'set', properties
Alias a person to another "identity" in Kissmetrics. Updates the current
instance's person
attribute to the new identity.
http://support.kissmetrics.com/apis/common-methods#alias
newIdentity
(String): A new identifier to map to the @person
set on
the current instance.
km.alias('evan+newemail@example.com')
alias: (newIdentity) ->
instanceToReturn = @_generateQuery 'alias', _n: newIdentity
@person = newIdentity
return instanceToReturn
Generic wrapper for HTTPS requests that abstracts the differences between requests made in Node and in a browser.
args
(Object): Key value pairs of URL pieces; only host
and
path
are used, and host
is required. _httpsRequest: (args) ->
url = "https://#{args.host}/#{args.path || ''}"
if NODEJS is on then https.get url else (new Image()).src = url
Ensures that reserved keys that are used (_k
for API key and _p
for person) are present and set correctly, regardless of whether they
were in the original data.
http://support.kissmetrics.com/apis/specifications.html
data
(Object): Specific data being recorded about this person. _validateData: (data) ->
if @apiKey
data._k = @apiKey
else
throw new Error 'API key required' unless @batchClient
if @person then data._p = @person else throw new Error 'Person required'
Prepare data to be sent to Kissmetrics. For immediate queries, we convert to a URL path and query string, then make the HTTP request. For batch queries, we add a timestamp and append the query object to the queue.
type
(String): Type of data being sent (record
, set
or alias
).
data
(Object): Specific data being recorded about this person.
_generateQuery: (type, data) ->
@_validateData data
if @batchClient
batchData = data
batchData.__type = type
@batchClient.add batchData
else
queryParts = for key, val of data
[key, val] = (encodeURIComponent param for param in [key, val])
"#{key}=#{val}"
queryString = queryParts.join '&'
queryType = KissmetricsClient.QUERY_TYPES[type]
@queries.push @_httpsRequest
host: KissmetricsClient.HOST
path: "#{queryType}?#{queryString}"
return @
Make KissmetricsClient
available either as a Node module or a property
on the current context in the browser.
// Node.js
KM = require('kissmetrics')
kmClient = new KM('apiKey', 'evan')
// Browser
kmClient = new window.KissmetricsClient('apiKey', 'evan')
if NODEJS is on
module.exports = KissmetricsClient
else
@KissmetricsClient = KissmetricsClient