saucy-kiss

Saucy-kiss is an extension to the Saucy gem for tracking your SaaS events in KISSmetrics.

It depends on the unofficial KISSmetrics gem.

Features and assumptions

We assume that:

Supported events

Saucy-kiss records all the KISSmetrics SaaS events:

Future work

TODO: Additional events provided by Saucy:

TODO: And events provided by Clearance:

TODO: Examples of additional meta-events?:

Identity

It will identify users to the current account wherever possible, and as anonymous otherwise. KISSmetrics will correctly handle aliasing between anonymous and named identities, and distinguishing between successive named identites, such as when you switch accounts. For more information, see:

support.kissmetrics.com/advanced/identity-management

Installation

In your Gemfile:

gem "saucy-kiss"

Then:

$ bundle

Implementation in your application

Add an initializer in config/initializers/saucy_kiss.rb:

Rails.configuration.after_initialize do
  Saucy::Notifications.register_observer(Saucy::Kiss::Observer.new({
    'staging'    => 'abc123',
    'production' => 'def456'
  }[Rails.env]))
end

Add a filter to each request in ApplicationController:

include Saucy::Kiss::ControllerFilters

Emit KISSmetrics javascript into your view (note the %== or equivalent html_safe):

<%== km.js! %>

The KISSmetrics javascript is asynchronous, so it’s safe to load at the top of your page.

Note: Saucy::Kiss will automatically instantiate the Snogmetrics gem like this:

api_key = Saucy::Kiss::API_KEYS[Rails.env]
session = data[:request].session
Snogmetrics::KissmetricsApi.new(api_key, session, snogmetrics_output_strategy)
# snogmetrics_output_strategy returns :console_log in development, :array in test, and
# :live otherwise.

and the Kissmetrics gem like this:

Kissmetrics::HttpClient.new(Saucy::Kiss::API_KEYS[Rails.env])

Customization

You may like to customize the events delivered to KISSmetrics. For example, you may want to track the referring ad campaign in a Signed Up event.

To do this, instead of using the Saucy::Kiss::Observer directly, create a subclass of the observer and register it instead:

class MyAppObserver < Saucy::Kiss::Observer
  def account_created(data)
    javascript_client(data).record('Signed Up', {
      'Plan Name' => data[:account].plan.name,
      'Plan Price' => data[:account].plan.price,
      'Is Trial Plan?' => data[:account].plan.trial,
      'Campaign Source' => data[:request].session[:campaign_source]
    })
  end
end

Rails.configuration.after_initialize do
  Saucy::Notifications.register_observer(MyAppObserver.new({
    'staging'    => 'abc123',
    'production' => 'def456'
  }[Rails.env]))
end

How it works

Saucy accepts observers in its configuration and publishes events for the SaaS events it implements. This gem implements an observer for these events, which your application registers in an initializer.

Saucy-kiss distinguishes between in-request events and out-of-request events, because it prefers delivering events to KISSmetrics via the JS API where possible; this is only possible for in-request events.

Using the snogmetrics gem, we record to the KISSmetrics JS API from within the request/response cycle by storing identity, events, and properties in the session and rendering them into your view as JS calls, similar to the Rails flash.

Using the kissmetrics gem, we record to the KISSmetrics HTTP API from outside the request/response cycle (think billing callbacks, or queued operations) delivered directly.

Contributing to saucy-kiss

Copyright © 2011 Jason Morrison. See LICENSE.txt for further details.