Merge pull request #18 from andreas-marschke/feature/guid

GUID.js: set a GUID cookie for unique users throughout a web application session
bluesmoon · Dec 23, 2014 · c1f3384 · c1f3384
2 parents aa2eb79 + 7c0fbb7
commit c1f3384
Show file tree

Hide file tree

Showing 2 changed files with 116 additions and 0 deletions.
diff --git a/doc/api/GUID.html b/doc/api/GUID.html
@@ -0,0 +1,71 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv="Content-type" content="text/html; charset=utf-8">
+  <title>The GUID API</title>
+  <link rel="stylesheet" type="text/css" href="../boomerang-docs.css"
+</head>
+<body>
+  <span style="float:right;"><a href="../">All Docs</a> | <a href="index.html">Index</a></span>
+  <h1>The Clicks Plugin</h1>
+  <p>The <code>GUID</code> Plugin adds a tracking cookie to the user that will be sent to the beacon-server as cookie</p>
+  <p>The <code>GUID</code> API is encapsulated in the <code>BOOMR.plugins.GUID</code> namespace </p>
+
+  <h2 id="config">Configuration</h2>
+  <p>
+    The GUID plugin configuration is contained in the <code>GUID</code> namespace in the initial Boomerang configuration Object. 
+  </p>
+  <p>See <a href="../howtos/howto-6.html">"Howto #6 &mdash; Configuring boomerang"</a> for more information on how to configure Boomerang</p>
+
+  <dl>
+    <dt>cookieName</dt>
+    <dd>
+      <strong>[required]</strong>
+      The name of the cookie to be set in the browser session
+    </dd>
+    <dt>expires</dt>
+    <dd>
+      <strong>[optional]</strong>
+      An expiry time for the cookie in seconds. By default 7 days.      
+    </dd>
+  </dl>
+
+<h2 id="methods">Methods</h2>
+
+<dl class="api">
+
+  <dt>init(oConfig)</dt>
+  <dd>
+    <p>
+      Called by the <a href="BOOMR.html#init">BOOMR.init()</a> method to configure the clicks plugin.
+    </p>
+    <pre>
+      BOOMR.init({
+        GUID: {
+          cookieName: "boomerang-guid",
+	  expires: 6000
+        }
+      });
+    </pre>
+    <h3>Parameters</h3>
+    <dl>
+      <dt>oConfig</dt>
+      <dd>The configuration object passed in via <code>BOOMR.init()</code>.  See the <a href="#config">Configuration section</a> for details.
+    </dl>
+    <h3>Returns</h3>
+    <p>
+      a reference to the <code>BOOMR.plugins.GUID</code> object, so you can chain methods.
+    </p>
+  </dd>
+
+
+  <h2 id="beacon">Beacon Parameters</h2>
+  <p>
+    None: no beacon parameters will be set cookies will be sent in the HTTP Header
+  </p>
+
+  <p class="perma-link">
+    The latest code and docs is available on <a href="http://github.com/lognormal/boomerang/">github.com/lognormal/boomerang</a>
+  </p>
+</body>
+</html>
diff --git a/plugins/GUID.js b/plugins/GUID.js
@@ -0,0 +1,45 @@
+/*
+ Tag users with a unique GUID
+*/
+(function(w) {
+
+    var impl = {
+	expires:  604800,
+	cookieName: "GUID",
+	generate: function() {
+	    function s4() {
+		return Math.floor((1 + Math.random()) * 0x10000).toString(16).substring(1);
+	    };
+
+	    return s4() + s4() + '-' + s4() + '-' + s4() + '-' + s4() + '-' + s4() + s4() + s4();
+	}
+    };
+
+    BOOMR.plugins.GUID = {
+	init: function(config) {
+	    var properties = ["cookieName", "expires"];
+	    BOOMR.utils.pluginConfig(impl, config, "GUID", properties);
+	    BOOMR.info("Initializing plugin GUID " + impl.cookieName , "GUID");
+
+	    if(!BOOMR.utils.getCookie(impl.cookieName)) {
+		BOOMR.info("Could not find a cookie for " + impl.cookieName, "GUID");
+
+		var guid = impl.generate();
+
+		if (!BOOMR.utils.setCookie(impl.cookieName,guid, impl.expires)) {
+		    BOOMR.subscribe("before_beacon", function() {
+			BOOMR.utils.setCookie(impl.cookieName,guid, impl.expires);
+		    });
+		}
+
+		BOOMR.info("Setting GUID Cookie value to: " + guid + " expiring in: " + impl.expires + "s", "GUID");
+	    } else {
+		BOOMR.info("Found a cookie named: " + impl.cookieName + " value: " + BOOMR.utils.getCookie(impl.cookieName) , "GUID");
+	    }
+	    return this;
+	},
+	is_complete: function() {
+	    return true;
+	}
+    };
+}(this));