Merge pull request #5 from bilbof/1.1.0

Version 1.1.0

LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Bill Franklin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -7,11 +7,18 @@ A lightweight JavaScript library for preserving user data from first website vis
 The library stores data such as `utm_medium`, `landing_page` and `referrer` in a localStorage object, and makes the object available via a handy API with the following methods:
 
 ```
-Purser.create() // automatically called on first website visit
-Purser.fetch() // returns the object
-Purser.convert(obj) // returns the object updated with conversion data
-Purser.update(obj) // lets you add additional parameters to the object
-Purser.destroy // removes the object from localStorage
+purser.create() // automatically called on first website visit
+purser.fetch() // returns the object
+purser.convert(obj) // returns the object updated with conversion data
+purser.update(obj) // lets you add additional parameters to the object
+purser.destroy() // removes the object from localStorage
+
+~~ NEW in version 1.1.0: track visits and pageviews ~~
+purser.visits.create() // adds a visit instance to the object, called automatically if has been over 30 minutes since the most recent visit.
+purser.visits.all() // returns an array of all visits
+purser.visits.fetch(id) // Fetch a specified visit
+purser.visits.update(id, obj) // Update a specified visit with data in an object
+purser.visits.delete(id) // Delete a specified visit
 ```
 
 View a live example at [http://purser.herokuapp.com/](http://purser.herokuapp.com/?utm_medium=github&utm_source=github_repo_example).
@@ -22,7 +29,7 @@ View a live example at [http://purser.herokuapp.com/](http://purser.herokuapp.co
 git clone https://github.com/bilbof/purser
 ```
 
-1. Add [purser.js](https://github.com/bilbof/purser/blob/master/purser.js) to every page on your website. When a visitor creates an account, call purser.convert(obj) and add the user to your CRM/ChartMogul with attributes returned.
+1. Add [purser.min.js](https://github.com/bilbof/purser/blob/master/purser.min.js) to every page on your website. When a visitor creates an account, call purser.convert(obj) and add the user to your CRM/ChartMogul with attributes returned.
 2. When a visitor creates an account, call purser.convert(obj) to get the visitor's marketing attributes
 3. Add the user's marketing attributes to them in your CRM or app
 
@@ -50,7 +57,7 @@ The `attributes` object in the example above would look something like this:
 
 ```js
 {
-	"first_website_visit": "2017-02-19T17:52:18.088Z",
+	"first_website_visit": "2017-08-10T17:52:18.088Z",
 	"referrer": "www.google.co.uk",
 	"browser_timezone": 0,
 	"browser_language": "en-GB",
@@ -59,8 +66,18 @@ The `attributes` object in the example above would look something like this:
 	"screen_width": 1280,
 	"utm_medium": "google_search_ads",
 	"utm_source": "google",
-	"signup_button": "red-signup-button",
-	"converted_at": "2017-02-19T17:52:41.981Z",
+	"sign_up_button": "green-button",
+	"converted_at": "2017-08-10T17:52:41.981Z",
+  "visits_at_conversion": 12,
+  "pageviews": 17,
+  "last_visit": "2017-08-10T17:45:00",
+  "visits": [<array of visit objects>],
 	"conversion_page": "http://localhost:5000/signup"
 }
 ```
+
+## Contributing
+
+If you would like to contribute, PLEASE DO! Just create a [Pull Request](https://github.com/bilbof/purser/compare) once you've made your changes.
+
+Want a feature added, but would prefer not to do it yourself? [Create an Issue](https://github.com/bilbof/purser/issues/new).

example/public/javascripts/purser.js

@@ -1,51 +1,125 @@
 (function (window) {
   "use strict";
-  var params = ['utm_source', 'utm_medium', 'utm_name', 'utm_term', 'utm_campaign', 'utm_content'];
-  var purser = window.purser || window.purser || {
+  var params = ["utm_source", "utm_medium", "utm_name", "utm_term", "utm_campaign", "utm_content"];
+  var purser = window.purser || window.Purser || {
     fetch: function(){
-      return JSON.parse(window.localStorage.getItem("purser_visitor"))
+      return JSON.parse(window.localStorage.getItem("purser_visitor"));
     },
     destroy: function(){
       return window.localStorage.removeItem("purser_visitor");
     },
-    convert: function(obj){
+    convert: function(obj) {
       var attributes = this.update(obj);
-      attributes['converted_at'] = new Date().toISOString();
-      attributes['conversion_page'] = window.location.origin + window.location.pathname;
-      window.localStorage.setItem('purser_visitor', JSON.stringify(attributes));
+      attributes.converted_at = new Date().toISOString();
+      attributes.conversion_page = window.location.origin + window.location.pathname;
+      attributes.visits_at_conversion = (attributes.visits || []).length;
+      attributes.pageviews_before_conversion = attributes.pageviews || 0;
+      window.localStorage.setItem("purser_visitor", JSON.stringify(attributes));
       return attributes;
     },
-    update: function(obj){
-      var attributes = this.fetch()
+    update: function(obj) {
+      var attributes = this.fetch();
+      if (!attributes) { attributes = purser.create(); }
       for (var key in obj) {
         if (obj.hasOwnProperty(key)) {
           attributes[key] = obj[key];
         }
       }
-      window.localStorage.setItem('purser_visitor', JSON.stringify(attributes));
+      window.localStorage.setItem("purser_visitor", JSON.stringify(attributes));
       return attributes;
     },
-    create: function(){
+    createInstance: function() {
       var attributes = {
-        first_website_visit: new Date().toISOString(),
         referrer: document.referrer.length ? document.referrer : "direct",
-        browser_timezone: new Date().getTimezoneOffset(),
+        browser_timezone: new Date().getTimezoneOffset()/60,
         browser_language: window.navigator.language,
         landing_page: window.location.origin + window.location.pathname,
         screen_height: window.screen.height,
-        screen_width: window.screen.width
-      }
+        screen_width: window.screen.width,
+      };
       for (var i = 0; i < params.length; i++) {
         var param = params[i];
         param = param.replace(/[\[\]]/g, "\\$&");
         var regex = new RegExp("[?&]" + param + "(=([^&#]*)|&|#|$)");
         var results = regex.exec(window.location.href);
         if (results && results[2]) attributes[param] = decodeURIComponent(results[2].replace(/\+/g, " "));
       }
-      window.localStorage.setItem('purser_visitor', JSON.stringify(attributes));
       return attributes;
+    },
+    create: function() {
+      var attributes = this.createInstance();
+      attributes.last_visit = parseInt(new Date().getTime()/1000);
+      attributes.pageviews = 1;
+      attributes.first_website_visit = new Date().toISOString();
+      window.localStorage.setItem("purser_visitor", JSON.stringify(attributes));
+      return attributes;
+    },
+    visits: {
+      recently: function() {
+        var attributes = purser.fetch();
+        if (!attributes.last_visit) return false;
+        var timeDiffInHours = (parseInt(new Date().getTime()/1000) - attributes.last_visit)/3600;
+        return timeDiffInHours < 0.5; // last visited less than half an hour ago.
+      },
+      create: function() {
+        var attributes = purser.fetch();
+        attributes.visits = attributes.visits || [];
+        var visit = purser.createInstance();
+        visit.id = (((1+Math.random())*0x10000)|0).toString(16).substring(1);
+        visit.date = new Date().toISOString();
+        attributes.visits.push(visit);
+        attributes.last_visit = parseInt(new Date().getTime()/1000);
+        purser.update(attributes);
+        return attributes;
+      },
+      fetch: function(id) {
+        var attributes = purser.fetch();
+        var visit = attributes.visits.filter(function(visit) {
+          return visit.id === id;
+        })[0];
+        visit.index = attributes.visits.map(function(visit) {
+          return visit.id;
+        }).indexOf(id);
+        return visit;
+      },
+      update: function(id, obj) {
+        var visit = purser.visits.fetch(id);
+        var attributes = purser.fetch();
+
+        for (var key in obj) {
+          if (obj.hasOwnProperty(key)) {
+            visit[key] = obj[key];
+          }
+        }
+        attributes.visits[visit.index] = visit;
+        return purser.update(attributes);
+      },
+      delete: function(id) {
+        var attributes = purser.fetch();
+        var visit = purser.visits.fetch(id);
+        attributes.visits = attributes.visits.splice(visit.index, 1);
+        return purser.update(attributes);
+      },
+      all: function() {
+        var attributes = purser.fetch();
+        return attributes.visits || [];
+      }
+    },
+    pageviews: {
+      add: function() {
+        var attributes = purser.fetch();
+        attributes.pageviews = attributes.pageviews + 1 || 1;
+        return purser.update(attributes);
+      }
     }
   };
-  if (!purser.fetch()) purser.create()
+  if (!purser.fetch()) {
+    purser.create();
+  } else {
+    if (!purser.visits.recently()) {
+      purser.visits.create();
+    }
+    purser.pageviews.add();
+  }
   window.purser = purser;
 }(window));

example/views/index.jade

@@ -8,9 +8,15 @@ block content
   p The library stores data such as <i>utm_medium</i>, <i>landing_page</i> and <i>referrer</i> in a localStorage object, and makes the object available via a handy API with the following methods:
   pre #{title}.create() // automatically called on first website visit
     | #{title}.fetch() // returns the object
-    | #{title}.convert() // returns the object updated with conversion data
+    | #{title}.convert(obj) // returns the object updated with conversion data
     | #{title}.update(obj) // lets you add additional parameters to the object
-    | #{title}.destroy // removes the object from localStorage
+    | #{title}.destroy() // removes the object from localStorage
+    | #{title}.visits.create() // adds a visit instance to the object, called automatically if has been over 30 minutes since the most recent visit.
+    | #{title}.visits.all() // returns an array of all visits
+    | #{title}.visits.fetch(id) // Fetch a specified visit
+    | #{title}.visits.update(id, obj) // Update a specified visit with data in an object
+    | #{title}.visits.delete(id) // Delete a specified visit
+
   h3 Usage
   p Add the library to every page on your website. When a visitor creates an account, call purser.convert() and add the user to your CRM/ChartMogul with attributes returned.
   ol
@@ -25,15 +31,18 @@ block content
     .form-group
         input( type="text" placeholder="Your Name" required).form-control#name
     .form-group
-        input(type="submit" value="Demo Create Account").btn.btn-primary#test
+        <a class="btn btn-primary" id="test">Demo Create Account</a>
+        <a class="btn btn-default" id="test-visit">Add a visit</a>
+        <a class="btn btn-pink" id="test-delete">Delete object</a>
     pre#result
 
   script(src="/javascripts/purser.js")
   script.
     var submit = document.getElementById('test');
-    submit.addEventListener('click', function(e){
-      e.preventDefault();
-
+    var visit = document.getElementById('test-visit');
+    var remove = document.getElementById('test-delete');
+
+    function post(data){
       var xhr = new XMLHttpRequest();
       xhr.open("POST", "/test");
       xhr.setRequestHeader("Content-Type", "application/json");
@@ -43,12 +52,31 @@ block content
         }
       }
 
-      xhr.send(JSON.stringify({
+      xhr.send(JSON.stringify(data));
+    }
+
+    submit.addEventListener('click', function(e){
+      e.preventDefault();
+      post({
         name: document.getElementById('name').value || "Not given",
         lead_created_at: new Date().toISOString(),
         purser_attributes: purser.convert({
           sign_up_button: "green-button"
         })
-      }));
+      })
+    })
+
+    visit.addEventListener('click', function(e){
+      e.preventDefault();
+      post({
+        name: document.getElementById('name').value || "Not given",
+        visit_button_clicked_at: new Date().toISOString(),
+        purser_attributes: purser.visits.create()
+      });
+    })
 
+    remove.addEventListener('click', function(e){
+      e.preventDefault();
+      purser.destroy();
+      document.getElementById('result').innerText = ""
     })

package.json

@@ -1,6 +1,6 @@
 {
   "name": "purser",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A lightweight JavaScript library for preserving user data from first website visit to signup.",
   "main": "pursor.js",
   "scripts": {