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:

You want the KISSmetrics JS on the page at all times, so you can define events in KISSmetrics, use their Google Analytics tie-in, etc.
You would like to track events using the JS API as much as possible, to take advantage of KISSmetrics' anonymous identity tracking, automatic handling of the "Visited Site" metric, bot/crawler blacklisting, etc.

Supported events

Saucy-kiss records all the KISSmetrics SaaS events:

Visited Site (handled automatically by the KISSmetrics JS library)
Signed Up
Upgraded / Downgraded (distinguished by plan price)
Billed
Canceled
Activated
- Called the first time that account.activated is set to true. It should be set once you are providing value to the user, so for Trajectory this might be when the user creates their first story, while for Copycopter an account might be activated once the user is syncing data to the client.
Viewed Plan (plan_viewed)
Viewed Plan List (plan_list_viewed)
- Called by Saucy's PlansController

Future work

TODO: Additional events provided by Saucy:

Invited New User
Accepted Invite
Tried to Exceed Project Limit

TODO: And events provided by Clearance:

Signed In
Signed Out

TODO: Examples of additional meta-events?:

Give example of Visit Retention (> 1 signins per month with a Visit model and Clearance instrumentation)

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:

http://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

Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
Fork the project
Start a feature/bugfix branch
Commit and push until you are happy with your contribution
Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.