README.md in sojourn-0.0.7 vs README.md in sojourn-0.1.0
- old
+ new
@@ -1,6 +1,6 @@
-# Sojourn
+# Sojourn [](https://travis-ci.org/smudge/sojourn) [](https://codeclimate.com/github/smudge/sojourn) [](https://codeclimate.com/github/smudge/sojourn/coverage)
Simple source & event tracking for Rails. This gem automatically tracks *sojourners*
(i.e. unique visitors) based on:
* Referer
@@ -17,52 +17,30 @@
Sojourn assigns each *sojourner* a UUID, which is tracked across requests. All events are
associated with this UUID and with the current user's ID (if logged-in).
Events (`Sojourn::Event`) consist of a name, a set of properties (key-value hash) and information
about the request. In the current ActiveRecord implementation, requests (`Sojourn::Request`) can
-be queried separately and may have many events. Requests also track browser (`Sojourn::Browser`)
-and campaign (`Sojourn::Campaign`) info as unique models. See 'Usage' below for the details
-of these models.
+be queried separately and may have many events. See 'Usage' below for the details of these models.
## Usage
```ruby
# Track a custom event (highly encouraged!):
sojourn.track! 'clicked call-to-action', plan_choice: 'enterprise'
+# If you don't have access to a controller context (i.e. the event is not occurring during a web
+# request), you can still track a raw event like this:
+
+Sojourn.track_raw_event! 'subscription expired', plan: 'enterprise', customer_id: 'xyb123'
+
+# Read events using ActiveRecord
e = Sojourn::Event.last
e.name # event name (e.g. 'clicked call-to-action')
e.sojourner_uuid # uuid tracked across requests, stored in cookie
e.user # User or nil
e.properties # key-value hash (e.g. "{ plan_choice: 'enterprise' }")
-e.request # Sojourn::Request object
-
-r = Sojourn::Request.last
-r.referer
-r.host
-r.path
-r.controller
-r.action
-r.params
-r.method
-r.ip_address
-r.campaign # Sojourn::Campaign object (nil if no campaign detected)
-r.browser # Sojourn::Browser object
-
-b = Sojourn::Browser.last
-b.known? # whether or not the browser was detected successfully
-b.user_agent
-b.name
-b.version
-b.platform
-b.bot?
-
-c = Sojourn::Campaign.last
-c.path # Base path (e.g. '/posts/2')
-c.params # Notable (tracked) params, sorted. (Typically utm-style, but configurable.)
-
```
## Default Events
The three built-in events are as follows:
@@ -79,10 +57,46 @@
* The referer is from an external source (i.e. not the current `request.host`)
* The request contains tracked (utm-style) parameters. (These can be configured in the `sojourn.rb`
initializer.)
+## Properties
+
+In addition to properties that you manually add, events will automatically include data about
+the current web request. An example looks like this:
+
+```json
+{
+ "custom_property":"value",
+ "request":{
+ "uuid":"5e698f6ca74a016c49ca6b91a79cada7",
+ "host":"example.com",
+ "path":"/my-news",
+ "controller":"news",
+ "action":"index",
+ "method":"get",
+ "params":{
+ "utm_campaign":"daily_updates",
+ "page":"1"
+ },
+ "referer":"https://mail.google.com",
+ "ip_address":"42.42.42.42",
+ "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/48.0.2564.48 Safari/537.36"
+ },
+ "browser":{
+ "bot":false,
+ "name":"Chrome",
+ "known":true,
+ "version":"48",
+ "platform":"mac"
+ },
+ "campaign":{
+ "utm_campaign":"daily_updates"
+ }
+}
+```
+
## Installation
Add this line to your application's Gemfile:
```ruby
@@ -113,6 +127,5 @@
* Assumes `User` and `current_user` convention for user tracking.
* Assumes that if `request.referer` does not match `request.host`, the referer is external to your
website.
* Relies solely on cookies to track visitor UUID across requests (no JS, fingerprinting, etc)
* Relies on ActiveRecord for storage. (At a bigger scale, append-only logs are preferred)
-* There are no tests.