Ruby Library

Our Ruby Library has the basic functionality laid out in our API specifications. It allows you to record events, set properties and alias users. However, you might miss these features from our JavaScript library:

• No built-in mechanisms for generating and saving identities for your users
• No built-in mechanisms for automatically tying together anonymous and named identities. This can still be done manually with the alias API call - please refer to our guide for managing identities.
• No built-in mechanisms for running A/B tests
• No automatic triggering of Events (such as detecting Search Engine traffic)

For these reasons we recommend our JavaScript Library to our users, even if you are running Ruby on Rails, and to use the Ruby Library for recording events that occur server-side (account Upgrades may be an example of one such event). You might also consider looking at other APIs our customers have created.

Setup

You can download a copy of the API from

http://github.com/kissmetrics/km

You will need your API key which you can find in your site settings.

Usage

Before calling any of the common methods you must call KM.init with a valid API key:

KM.init(string KM_KEY [, options])

The available options are:

• log_dir - sets the logging directory. Default is '/tmp'. Please make sure that the directory exists, and that whatever web process is writing to the log has permission to write to that directory. The log file will contain a list of the URLs that would be requested (trk.kissmetrics.com URLs - please refer to API Specifications).
• use_cron - toggles whether to send data directly to KISSmetrics, or log to a file and send in the background via cron (see Sending Data with Cron for more information). Default is false, which means data is sent directly to KISSmetrics. Using cron is optional, but recommended.
• to_stderr - allows toggling of printing output to stderr. Default is true.
• dryrun - New option as of November 25, 2012. Toggles whether to send data to KISSmetrics, or just log it to a file to review for debugging. Default is false, which means data is sent to KISSmetrics, regardless of whether you're working in a production or development environment.
• env - Updated option as of November 25, 2012. The environment variable now just helps us name the log files that store the history of event requests. This uses the Rails and Rack variables to determine if your Ruby environment is in development. If the Rails and Rack variables are not available, we default to production.

Example:

KM.init("this is your key", :log_dir => '/var/logs/kissmetrics/')

Example Calls

KM.identify('bob@bob.com')
KM.record('Viewed Homepage')
KM.record('Signed Up', {'Plan' => 'Pro', 'Amount' => 99.95})
KM.record('Signed Up', {'_d' => 1, '_t' => 1234567890})
KM.set({:gender=>'male', 'Plan Name' => 'Pro'})
KM.alias('bob', 'bob@bob.com')

Troubleshooting

If you were watching for the events in KISSmetrics Live and did not see them, it helps to review what our library logged. In the log directory, you may see these files:

• kissmetrics_production_sent.log
• kissmetrics_production_query.log
• kissmetrics_production_error.log
• kissmetrics_development_sent.log
• kissmetrics_development_query.log
• kissmetrics_development_error.log

If you contact support to troubleshoot, please refer to the contents of these files, if possible.

• Ruby on Rails

  Here are two different methods of setting up KISSmetrics in your Ruby on Rails application.

• Heroku

  Considerations when setting up KISSmetrics for your Heroku application.

Contributed by Eric Fung