sojourn 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a5bcd732bdfc1df4fdd68744f4c807f894104848
-  data.tar.gz: 927a8ba15bd0948cb8c390c15b7c900785051a1f
+  metadata.gz: 9f2ae69a242be094ed09f87d8721b0b12c7369a4
+  data.tar.gz: 16deb25d1a1598c08cd96162a59ec25a344fde88
 SHA512:
-  metadata.gz: 469867e717db9bc51b25e1b414a711db552631225524e781a2c9a5d62e3faefdf2d8e0f77acd426aaa7ac094b62e35b7361ec5c761ed4dadaddf7ce8bba2d32b
-  data.tar.gz: 44d5346a2ccabc605e220af036077b2f9969213580bc04188852f5d6ee6ff4a2b3a6ea1bf566cefdaa0cde87177092d3892247448bafdc19703cf8f9c96dc3f4
+  metadata.gz: 99a18bf20addc6f178c68b9fc96a990c512ef6c1839c54755dc523327c77984dafedff591a122da996e536e030de6e247800f3643f00b9425c937c22770d7788
+  data.tar.gz: dc459a98a2a177b53aacebfd400b37853ad61c6da727ed48713884d1f7960c90146e7c362211391a551472aed00389038204920da5724ce5f9f2cc7d0ad7618b

data/README.md

@@ -11,16 +11,22 @@ Simple source & event tracking for Rails. This gem automatically tracks *sojourn
 
 ## How It Works
 
-**Everything is tracked in the form of events.** Yep, events all the way down.
-(See 'Why Events?' below for the reasoning behind this.)
+Whenever a new visitor ("sojourner") arrives to the site, an event is tracked containing
+basic data about their browser and where they came from. Similar events are also tracked
+whenever a user logs in, logs out, or visits again from an external site. In addition,
+you can track a custom event anytime a visitor does something of interest to you.
 
-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).
+Ultimately, rather than storing parts of the data in separate tables, **all data is
+tracked in the form of events.** Yep, events all the way down. (See 'Why Events?' below
+for the reasoning behind this.)
 
-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. See 'Usage' below for the details of these models.
+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). The current
+request is also assigned a UUID (which defaults to the `X-Request-ID` header).
 
+Events consist of an event name (defining a collection of events), a session UUID,
+and a set of properties (key-value data) which includes information about the request.
+In the PostgreSQL implementation, we use a `JSONB` column to store the key-value data.
 
 ## Usage
 
@@ -28,17 +34,16 @@ be queried separately and may have many events. See 'Usage' below for the detail
 # 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' }")
+
+# 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'
 ```
 
 ## Default Events
@@ -51,7 +56,7 @@ The three built-in events are as follows:
 '!logged_out' # The sojourner has logged-out.
 ```
 
-A `'!sojourning'` event takes place whenever any of the following is true:
+A `'!sojourning'` event takes place whenever any of the following conditions is met:
 
 * The sojourner has never been seen before (i.e. direct traffic of some kind)
 * The referer is from an external source (i.e. not the current `request.host`)
@@ -116,10 +121,17 @@ To install migrations and the `sojourn.rb` initializer, execute:
 The idea is that, at a certain scale, this kind of tracking should be dumped directly into
 append-only logs (or an event bus / messaging queue) for asynchronous processing.
 
-This is made easier when everything can be represented, at a basic level, as discrete events.
-In theory, it works with just about any data store, and makes for easy time series and funnel
-analysis. I'd like to move away from ActiveRecord at some point and open up the door for other,
-highly scalable data backends.
+This is made easier when everything can be represented, at a basic level, as a set of discrete
+events. In theory, it works with just about any data store, and makes for easy time series and
+funnel analysis. I'd like to move away from ActiveRecord at some point and open up the door for
+other, more horizontally scalable data backends, ideally with a focus on streaming data (e.g.
+Kafka combined with Samza or Storm).
+
+An added benfit of storing the start of each visit as its own event in the series (i.e. the
+built-in `!sojourning` event) is that you can change the length of your visit window after
+the fact and re-run your analysis. The more traditional approach is to tag each event with
+some kind of incrementing visit ID, which forces you into defining what a "unique visit"
+means for your product before you've even collected any data.
 
 ## Current Limitations (i.e. the 'todo' list)
 

data/lib/sojourn/request.rb

@@ -31,7 +31,8 @@ module Sojourn
 
     def browser_data
       return @browser_data if @browser_data
-      @browser_data = {
+      @browser_data = { known: false } unless browser
+      @browser_data ||= {
         name: browser.name,
         version: browser.version,
         platform: browser.platform,

data/lib/sojourn/version.rb

@@ -1,3 +1,3 @@
 module Sojourn
-  VERSION = '0.1.0'
+  VERSION = '0.1.1'
 end

data/spec/mocks/request.rb

@@ -50,7 +50,7 @@ module Mocks
     end
 
     def user_agent
-      opts[:user_agent] || CHROME_UA
+      opts.key?(:user_agent) ? opts[:user_agent] : CHROME_UA
     end
   end
 end

data/spec/tracker_spec.rb

@@ -21,17 +21,12 @@ module Sojourn
       its(:user_id) { is_expected.to eq(user.id) }
       its(:name) { is_expected.to eq(event_name) }
 
-      describe 'request' do
-        subject { Event.last.properties[:request] }
-
-        its([:params]) { is_expected.to eq('filtered' => true) }
-        its([:method]) { is_expected.to eq('get') }
-      end
-
       describe 'properties' do
         subject { Event.last.properties }
 
         its(:keys) { is_expected.to eq(%w(request browser bar)) }
+        its([:request, :params]) { is_expected.to eq('filtered' => true) }
+        its([:request, :method]) { is_expected.to eq('get') }
         its([:browser, :name]) { is_expected.to eq('Chrome') }
       end
     end
@@ -73,6 +68,19 @@ module Sojourn
 
         its(:name) { is_expected.to eq('!logged_out') }
       end
+
+      context 'when user agent not present' do
+        let(:request) { Mocks::Request.new(user_agent: nil) }
+
+        its(:name) { is_expected.to eq('!sojourning') }
+
+        describe 'properties' do
+          subject { Event.last.properties }
+
+          its([:browser, :known]) { is_expected.to be(false) }
+          its([:browser, :name]) { is_expected.to be_nil }
+        end
+      end
     end
 
     describe 'update_session!' do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sojourn
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Smudge
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-01-04 00:00:00.000000000 Z
+date: 2016-01-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler