Merge pull request #29 from jasonzissman/upgrade-to-2_0

Upgrade to 2.0

.gitignore

@@ -1 +1,3 @@
-bower_components/
+bower_components/
+debug.log
+node_modules

LICENSE

@@ -1,5 +1,5 @@
 MIT License (MIT)
-Copyright (c) 2016
+Copyright (c) 2017
 
 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:
 

README.md

@@ -1,17 +1,17 @@
 <h3>What is TimeMe.js?</h3>
 TimeMe.js is a JavaScript library that accurately tracks how long users interact with a web page.
-TimeMe.js disregards time spent on a web page if the user minimizes the browser or 
+It disregards time spent on a web page if the user minimizes the browser or 
 switches to a different tab. This means a more accurate reflection of actual 'interaction' time by 
 a user is being collected. Additionally, TimeMe.js disregards 'idle' time outs. If the user goes 
 idle (no page mouse movement, no page keyboard input) for a customizable period of time,
-then TimeMe.js will automatically ignore this time. This means no time will be reported
-where a web page is open but the user isn't actually interacting with it (such as when
-they temporarily leave the computer). These components put together create a much more accurate
-representation of how long users are actually using a web page.
+then TimeMe.js will automatically ignore this time. 
 
-Furthermore - TimeMe tracks time usage across multiple pages. This is particularly 
-useful when running a single page web application. You can get a list of all aggregate 
-times spent on all pages from TimeMe.js.
+This means no time will be reported where a web page is open but the user isn't actually interacting 
+with it (such as when they temporarily leave the computer). These components put together create a 
+much more accurate representation of how long users are actually using a web page.
+
+Furthermore - TimeMe supports tracking time across multiple pages. This is particularly 
+useful when running a single page web application.
 
 <h3>Demo</h3>
 You can see a demo of a timer using TimeMe.js 
@@ -20,25 +20,21 @@ You can see a demo of a timer using TimeMe.js
 <h3>Where do I get TimeMe.js?</h3>
 You can use Bower to install TimeMe (see next steps) and its dependencies.
 Alternatively, you can download the most recent copy at <a href="https://github.com/jasonzissman/TimeMe.js">the TimeMe Github project</a>.
-Notice you will also need a copy of <a href="https://github.com/serkanyersen/ifvisible.js">
-Serkanyersen's ifvisible.js project</a>. The ifvisible.js library is REQUIRED to allow
-TimeMe.js to work.
 
 <h3>How do I use TimeMe.js?</h3>
 
-First, obtain a copy of timeme.js and ifvisible.js. You can get both by installing TimeMe.js via Bower: <br/><br/>
-<div class="code-block"><pre><code>bower install timeme.js</pre></code></div><br/><br/>
+First, obtain a copy of timeme.js. You can do so by installing TimeMe.js via Bower: <br/><br/>
+<div class="code-block"><pre><code>bower install timeme.js</pre></code></div><br/>
 Then, simply include the following lines of code in your page's head element: <br/><br/>
-<div class="code-block"><pre><code>&lt;script src="ifvisible.js"&gt;&lt;/script&gt;
-&lt;script src="timeme.js"&gt;&lt;/script&gt;
+<div class="code-block"><pre><code>&lt;script src="timeme.js"&gt;&lt;/script&gt;
 &lt;script type="text/javascript"&gt;
- TimeMe.setIdleDurationInSeconds(30);
- TimeMe.setCurrentPageName("my-home-page");
- TimeMe.initialize(); 
+ TimeMe.initialize({
+ currentPageName: "my-home-page", // current page
+ idleTimeoutInSeconds: 30 // seconds
+ }); 
 &lt;/script&gt;</code></pre>
 </div><br/>
-This code both imports the TimeMe.js library and initializes it. Notice that
-this code sets the idle duration to 30 seconds, which means 30 seconds of user
+Notice that the code sets the idle duration to 30 seconds, which means 30 seconds of user
 inactivity (no mouse or keyboard usage on the page) will stop the timer. Also,
 we define a page name (my-home-page) to associate with the current timer.
 <br/><br/>
@@ -48,17 +44,55 @@ a complete breakdown of all of the available functionality. The most basic
 feature is to retrieve the time spent by the user on the current page:<br/><br/>
 <div class="code-block">
  <pre><code>var timeSpentOnPage = TimeMe.getTimeOnCurrentPageInSeconds();</code></pre>
-</div><br/>
+</div>
+TimeMe gives you a hook to execute a function after a user has been interacting with your
+page for a set period of time. Simply call TimeMe.callAfterTimeElapsedInSeconds():
+<div class="code-block">
+<pre><code>TimeMe.callAfterTimeElapsedInSeconds(15, function(){
+ console.log("The user has been using the page for 15 seconds! Let's prompt them with something.");
+});</code></pre>
+</div>
+TimeMe also lets you execute code when a user leaves the page (due to switching tabs, inactivity, etc.) and
+when he or she returns:
+<div class="code-block">
+<pre><code>// Executes the first 5 times a user leaves the page
+TimeMe.callWhenUserLeaves(function(){
+ console.log("The user is not currently viewing the page!");
+}, 5);
+
+// Executes every time a user returns
+TimeMe.callWhenUserReturns(function(){
+ console.log("The user has come back!");
+});
+</code></pre>
+</div>
+
+<h3>What do I do with the time I've tracked?</h3>
+
 In most cases you will want to store the time spent on a page for analytic purposes. You will
-therefore need to send the time spent on a page to the server at some point! When is
-the best time to do this? You can hook into the window.onbeforeunload event to do so.
-In most browsers this method is fired during a page's shut-down routine.
-Notice below that we use a synchronous request (not the usual asynchronous request) to guarantee
-the request to our server arrives before the page closes:<br/><br/>
+likely need to send the time spent on a page to a back-end server. 
+
+<h4>Using WebSockets to send times</h4>
+TimeMe.js has websocket reporting built into it. Your page will establish a websocket connection with your
+websocket server. TimeMe will end the connection and report the user's time when the user leaves. 
+Simply provide a few arguments to the initialize() method to enable it:<pre><code>TimeMe.initialize({
+ currentPageName: "my-home-page", // current page
+ idleTimeoutInSeconds: 30, // seconds 
+ websocktOptions: { // optional
+ websocketHost: "ws://your_host:your_port",
+ appId: "insert-your-made-up-app-id"
+ }
+});</code></pre>
+
+<h4>Using standard http requests to send time</h4>
+Alternatively you can issue an HTTP request to your back end server to report time.
+Note: the following example sends an HTTP request during the the window.onbeforeunload event.
+This approach may not work in all browsers as there is no guarantee that the request
+will complete before the browser terminates it.<br/><br/>
 <div class="code-block">
 <pre><code>window.onbeforeunload = function (event) {
  xmlhttp=new XMLHttpRequest();
- xmlhttp.open("POST","ENTER_URL_HERE",false);
+ xmlhttp.open("POST","ENTER_URL_HERE", true);
  xmlhttp.setRequestHeader("Content-type", "application/x-www-form-urlencoded");
  var timeSpentOnPage = TimeMe.getTimeOnCurrentPageInSeconds();
  xmlhttp.send(timeSpentOnPage);
@@ -67,10 +101,7 @@ the request to our server arrives before the page closes:<br/><br/>
 Using 'onbeforeunload' is by no means a requirement. You can hook into any other event
 or logical point in your application to send the time spent information to the server.
 <br/><br/>
-In a traditional web design where one static page is served for each request
-made by the client, any call to getTimeOnCurrentPageInSeconds() will be
-unique and valid for each page that imports and initializes TimeMe.js. Alternatively,
-if using a Single Page Application (SPA) design, TimeMe.js can have its timer stopped,
+If using a Single Page Application (SPA) design, TimeMe.js can have its timer stopped,
 page name switched, and the timer resumed (for the new page) with the following calls:<br/><br/>
 <div class="code-block">
 <pre><code>TimeMe.stopTimer();
@@ -98,32 +129,21 @@ performed a Bower install of TimeMe.js. Once you have installed QUnit, you can
 open the test files to execute the tests.
 </div>
 <div>
-<h3>Anyone to give credit to?</h3>
-TimeMe.js uses ifvisible.js. Take a look at 
-<a href="https://github.com/serkanyersen/ifvisible.js">serkanyersen's Github account</a> 
-if interested in just using the 'ifvisible' component of TimeMe that lets you know when a 
-user is actively viewing your page! 
-</div> 
 <div>
 <a name="API"></a>
-<h3>API</h3> 
+<h3>API</h3>
 <div class="code-block">
-<pre><code>TimeMe.setCurrentPageName(newPageName);</code></pre>
-Sets the page name to be associated with any future calls to timer. 
-<br/><br/>
-</div><br/> 
-<div class="code-block">
-<pre><code>TimeMe.setIdleDurationInSeconds(durationInSeconds);</code></pre>
-Sets the time (in seconds) that a user is idle before the timer is
-turned off. Set this value to -1 to disable idle time outs.
-<br/><br/>
-</div><br/> 
-<div class="code-block">
-<pre><code>TimeMe.initialize();</code></pre>
+<pre><code>TimeMe.initialize(options);
+// options.currentPageName // - Name of the page (home, about, etc.)
+// options.idleTimeoutInSeconds // - how much inactive time before user considered idle
+// options.websocktOptions: { // Turn on websocket reporting
+// websocketHost: "ws://your_host:your_port",
+// appId: "insert-your-made-up-app-id"
+// }</code></pre>
 Initializes the timer. Should only be called when first importing the
-library and beginning to time page usage.
+library and beginning to time page usage. All options are optional.
 <br/><br/>
-</div><br/> 
+</div><br/>
 <div class="code-block">
 <pre><code>var timeInSeconds = TimeMe.getTimeOnCurrentPageInSeconds();</code></pre>
 Retrieves the time spent (in seconds) on the current page.
@@ -133,7 +153,33 @@ Retrieves the time spent (in seconds) on the current page.
 <pre><code>var timeInSeconds = TimeMe.getTimeOnPageInSeconds(pageName);</code></pre>
 Retrieves the time spent (in seconds) on the indicated page.
 <br/><br/>
-</div><br/> 
+</div><br/>
+<div class="code-block">
+<pre><code>TimeMe.callAfterTimeElapsedInSeconds(timeInSeconds, callback);</code></pre>
+Sets up a handler that executes after the user has spent the specified time interacting with the page.
+<br/><br/>
+</div><br/>
+<div class="code-block">
+<pre><code>TimeMe.callWhenUserLeaves(callback, [[numberOfInvocations]]);</code></pre>
+Sets up a handler that executes when the user is no longer interacting with the page due to inactivity,
+switching tabs, or switching apps. You can optionally provide numberOfInvocations to limit how many times this executes.
+</div><br/>
+<div class="code-block">
+<pre><code>TimeMe.callWhenUserReturns(callback, [[numberOfInvocations]]);</code></pre>
+Sets up a handler that executes when the user returns to the page after inactivity,
+switching tabs, or switching apps. You can optionally provide numberOfInvocations to limit how many times this executes.<br/><br/>
+</div><br/>
+<div class="code-block">
+<pre><code>TimeMe.setCurrentPageName(newPageName);</code></pre>
+Sets the page name to be associated with any future calls to timer. 
+<br/><br/>
+</div><br/> 
+<div class="code-block">
+<pre><code>TimeMe.setIdleDurationInSeconds(durationInSeconds);</code></pre>
+Sets the time (in seconds) that a user is idle before the timer is
+turned off. Set this value to -1 to disable idle time outs.
+<br/><br/>
+</div><br/> 
 <div class="code-block">
 <pre><code>var timeSpentInfo = TimeMe.getTimeOnAllPagesInSeconds();</code></pre>
 Retrieves the time spent on all pages that have been recorded using TimeMe.js.
@@ -163,3 +209,10 @@ Clears all recorded times for all pages.
 <br/><br/>
 </div><br/> 
 </div> 
+<h3>Build Tools</h3>
+To minify the code, run the following:
+<div class="code-block">
+<pre><code>npm install uglify-js -g
+uglifyjs timeme.js --mangle --compress --support-ie8 --output timeme.min.js</code></pre>
+<br/><br/>
+</div><br/> 

bower.json

@@ -1,7 +1,7 @@
 {
  "name": "timeme.js",
  "main": "timeme.js",
- "version": "1.2.0",
+ "version": "2.0.0",
  "homepage": "https://github.com/jasonzissman/TimeMe.js",
  "authors": [
  "Jason Zissman"
@@ -19,9 +19,6 @@
  "test",
  "tests"
  ],
- "dependencies": {
- "ifvisible.js": "~1.0.4"
- },
  "devDependencies": {
  "qunit": "~1.20.0"
  }