Ruby Library

Ruby library

Our Ruby Library has the basic functionality laid out in our API specifications. It allows you to record events and set properties. 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.
  • 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

The best way to install the gem is using gem install kmts or by adding it to your Gemfile:

gem 'kmts', '~> 2.0.0'

The source of the gem is on Github.

Note: our previous km Ruby gem is not thread safe, so we recommend now using kmts.

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:

KMTS.init('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:

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

Example Calls

KMTS.record('bob@bob.com', 'Viewed Homepage')
KMTS.record('bob@bob.com', 'Signed Up', {'Plan' => 'Pro', 'Amount' => 99.95})
KMTS.record('bob@bob.com', 'Signed Up', {'_d' => 1, '_t' => 1234567890})
KMTS.set('bob@bob.com', {:gender=>'male', 'Plan Name' => 'Pro'})
KMTS.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.

Is anything on this page unclear? Suggest edits on Github!