Permalink
Browse files

Updated the documentation

  • Loading branch information...
1 parent e0f3a40 commit 6c13db64feb3c426bc0f0c638ef683fa32439bf6 @iconara committed Mar 30, 2010
View
@@ -1,24 +1,39 @@
# SNOGmetrics
-SNOGmetrics is a bridge between Rails and KISSmetrics JavaScript API.
+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?
+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 and add a line to your layout.
+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.
-## Installation
+## How do I use it?
1. `gem install snogmetrics`
2. Edit `config/environment.rb` and add `config.gem 'snogmetrics'`
-3. Edit your `ApplicationController` and add `include Snogmetrics`
-4. Edit your layout(s) and add `<% km_output_js! %>` where you keep your JavaScript includes.
-5. Replace all your `KM.record(...)` and `KM.identify(...)` calls in JavaScript with calls to `km_record(...)` and `km_identify(...)`
+3. Edit your layout(s) and add `<%= km.js! %>` where you keep your JavaScript includes.
+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.
+
+## Anything else I should know?
+
+Yes, SNOGmetrics will _not_ output the KISSmetrics API code unless `RAILS_ENV` is `production`. Instead it will output code that logs all calls to the console (if `console` is defined).
+
+In a future version this behaviour might be overrideable.
## Note on Patches/Pull Requests
View
@@ -1,2 +0,0 @@
-# SNOGmetrics example application
-
@@ -0,0 +1,7 @@
+# SNOGmetrics example application
+
+This is a small Rails application that uses SNOGmetrics. Look in `app/controllers/snogs_controller.rb` to see how you interact with the API from a controller, and look at `app/views/layouts/application.html.erb` to see the snipplet you need to add to your layout file.
+
+Because it's easier for me when I code I've added SNOGmetrics as a plugin in the `vendor/plugins` directory (by way of symlinks), but in a real application you would add the gem in `config/environment.rb` (there's a out-commented line there if you want to see how it's done).
+
+To set the KISSmetrics API key you need to add an initializer, see `config/initializers/snogmetrics.rb` for an example.
@@ -3,6 +3,11 @@
require File.join(File.dirname(__FILE__), 'boot')
Rails::Initializer.run do |config|
+ # Usually you would add SNOGmetrics by adding the gem here, but in this
+ # example app I have put the code as a plugin, because it's more convenient
+ # when I code new features.
+ #config.gem 'snogmetrics'
+
config.frameworks -= [:active_record, :active_resource, :action_mailer]
config.action_controller.session = {:key => '_snoggy_session', :secret => 'd08d2ef897ba8d7477bc3088dde396ac'}
end
@@ -1,5 +1,14 @@
+# This is where you configure SNOGmetrics. Just override the #kissmetrics_api_key
+# method of the module to return the API key.
module Snogmetrics
def kissmetrics_api_key
'abc123'
end
-end
+end
+
+# If you need to load the API from a YAML file, you can do something like the
+# following. It loads the key and puts it in a local variable, then it overrides
+# the #kissmetrics_api_key method with a closure that has access to the local
+# variable 'key'.
+#key = YAML.load(ERB.new(File.read('path/to/file.yml')).result)[RAILS_ENV].symbolize_keys[:kissmetrics_api_key]
+#Snogmetrics.send(:define_method, :kissmetrics_api_key) { key }

0 comments on commit 6c13db6

Please sign in to comment.