SNOGmetrics

SNOGmetrics is a bridge between Rails and KISSmetrics' JavaScript API.

But KISSmetrics has a Ruby API!

Yes, but it's not as good as the JavaScript one, they even say so themselves:

One thing to note about the Ruby API is that it is not as full featured as the JavaScript client. Therefore, in most cases we recommend using the JavaScript client. However, some things are easier to track server-side, therefore we have provided a basic Ruby client.

It's true, but why settle for either or?

SNOGmetrics works similarly to flash messages. Events are recorded and saved to the session, and are then sent when the next page is rendered. This way you get all of the benefits of the JavaScript API, but you can record events in your controllers. All you have to do is install this gem, configure it, and add a snipplet of code to your layout.

Rails 3+ How do I use it?

1. Add snogmetrics in your gemfile and run the bundle command to install it

2. Add an initializer file like the following under your config/initializers folder

    Snogmetrics.kissmetrics_api_key = "your-api-key-here"
   

3. Edit your layout(s) and add <%= km.js! %> in the body tag (this makes it work nicely with Turbolinks)

4. Replace all your KM.record(...) and KM.identify(...) calls in JavaScript with calls to km.record(...) and km.identify(...)

Have a look at the included example application to see it in action.

Does it use the asynchronous API?

Yes it does.

What if I want to call KISSmetrics from both my controllers and JavaScript?

Just do it. You need to make sure that the _kmq array exists, though. SNOGmetrics will define it where you place <%= km.js! %>, but that is usually at the bottom of the page (with the async API you could probably put it at the top if you wanted to), so if you want to add things to _kmq before that you need to define it yourself. Just add var _kmq = _kmq || [] and you're set.

What about A/B testing

SNOGmetrics implements #set, which is equivalent to _kmq.push(["set", ...]), the preferred way of recording which version a user saw in an A/B test. SNOGmetrics does not support the KM.ab function, because that's something you want to do in JavaScript only.

Anything else I should know?

Yes, SNOGmetrics will not output the KISSmetrics API code unless RAILS_ENV is production by default. Instead it will output code that logs all calls to the console (if console is defined).

If you'd like to change this behaviour, add the following to your initializer:

    Snogmetrics.output_strategy = :live

Note on Patches/Pull Requests

• Fork the project.
• Make your feature addition or bug fix.
• Add tests for it. This is important so I don't break it in a future version unintentionally.
• Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
• Send me a pull request. Bonus points for topic branches.

Copyright

Copyright (c) 2010 Theo Hultberg / Burt. See LICENSE for details.