Permalink
Browse files

first attempt

  • Loading branch information...
James A. Rosen
James A. Rosen committed Nov 30, 2010
1 parent a505f1e commit 381398f86c39911bc6ba5bdc80e2ea4fc7331ba1
Showing with 200 additions and 0 deletions.
  1. +22 −0 LISENCE
  2. +126 −0 README.md
  3. +52 −0 lib/jquery-saas-pulse-0.1.js
View
22 LISENCE
@@ -0,0 +1,22 @@
+Copyright (c) 2010 James A. Rosen, Zendesk
+
+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.
View
126 README.md
@@ -0,0 +1,126 @@
+## What ##
+
+A jQuery plugin that makes instrumenting your web application with
+[SaaSPulse](http://www.saaspulse.com/) metrics easy. SaaSPulse uses
+a 4-tuple to identify each event:
+
+ [ activity, module, organization, user ]
+
+jQuery-SaaSPulse will automatically track clicks and form submissions
+on any element that has data attributes for all four pieces of information.
+To reduce redundancy and make implementation easier, it will also
+search up the DOM tree to fill in missing pieces of information.
+
+## Installation ##
+
+Include SaaSPulse's SDR library:
+
+ <script src='//s3.amazonaws.com/saaspulse-cdn/sdr.js' defer></script>
+
+Initialize the SaaSPulse tracker:
+
+ jQuery(function() {
+ try {
+ var tracker = new __sdr(...);
+ } catch (err) {
+ var tracker = {
+ track: function() {},
+ identify: function() {}
+ }
+ }
+ });
+
+Include jQuery-SaasPulse:
+
+ <script src='/javascripts/jquery-saas-pulse-0.1.js' defer></script>
+
+## Usage ##
+
+### Basics ###
+
+To instrument tracking on only one element on a page, add four data
+attributes to that element and apply `instrumentTracking` to it:
+
+ <a href='#/foo/bar'
+ id='foo_bar'
+ data-saas-pulse-activity='bar'
+ data-saas-pulse-module='foo'
+ data-saas-pulse-organization='Example.org'
+ data-saas-pulse-user='Chloe'>Bar my Foo</a>
+
+ // whenever the <a> is clicked, the SaaSPulse SDR tracker is
+ // called with ('bar', 'foo', 'Example.org', 'Chloe')
+ $('#foo_bar').instrumentTracking();
+
+### Reducing Duplication ###
+
+In most applications, you'll want to instrument more than one element
+on a page and elements will share tracking properties -- particularly
+`organization` and `user`. In those cases, you can use the DOM tree's
+inherent structure to reduce duplication:
+
+ <body data-saas-pulse-organization='Example.org'
+ data-saas-pulse-user='Chloe'>
+ <section data-saas-pulse-module='foo'>
+ <form action='#/foo/bar' id='foo_bar' data-saas-pulse-activity='bar'>
+ <input type='submit' value='Bar my Foo' />
+ </form>
+ </section>
+ <aside data-saas-pulse-module='sidebar'>
+ <a href='#/baz' id='sidebar_baz' data-saas-pulse-activity='baz'>Baz</a>
+ </aside>
+ </body>
+
+ // Whenever the <form> is submitted, the SaaSPulse SDR tracker is
+ // called with ('bar', 'foo', 'Example.org', 'Chloe').
+ // Whenever the <a> is clicked, it is called with
+ // ('baz', 'sidebar', 'Example.org', 'Chloe').
+ $('#foo_bar, #sidebar_baz').instrumentTracking();
+
+### Less-Specific Selectors ###
+
+If you call `instrumentTracking()` on elements that don't have all four
+data attributes (either themselves or inherited from parents), no call
+will be made to SaaSPulse. Nonetheless, it is suggested that you be as
+specific as possible since the search up the DOM tree can become expensive
+when run on every single click on a page.
+
+### Manually Tracking an Activity ###
+
+You may want to track an event other than a `click` or form `submit`. If so,
+you can call `trackEvent` on an element, which will send a single tracking
+call to the SDR library. You can override the `activity`, `module`,
+`organization`, or `user` that would be fetched from data attributes by
+passing an `Object` hash with them to the `trackEvent` call.
+
+For example, say you want to track every time somebody
+fails to fill in a field on your sign-in form:
+
+ <body data-saas-pulse-organization='Example.org'
+ data-saas-pulse-user='Chloe'>
+ <form class='sign_in' data-saas-pulse-module='Sign-In'>
+ ...
+ </form>
+ </body>
+
+ $('form.sign_in input').blur(function() {
+ if ($(this).val() === '') {
+ $(this).trackEvent({ activity: 'skip-required' });
+ }
+ });
+
+
+### Custom Tracker Object ###
+
+By default, the plugin uses the global `tracker` object, as described by
+the SaaSPulse documentation. If you have namespaced your tracker, simply
+pass it to the `instrumentTracking` call:
+
+ MyApp.saasPulseTracker = ...
+
+ $('#foo,.bar).instrumentTracking(MyApp.saasPulseTracker);
+
+or, when manually tracking an activity, pass it as the `tracker` option
+in the `options` hash:
+
+ $(this).trackEvent({ tracker: MyApp.saasPulseTracker, activity: 'ignore' });
@@ -0,0 +1,52 @@
+jQuery.fn.extend({
+
+ // Adds SaaSPulse tracking to the current element.
+ // If the element is a form, adds an onSubmit handler;
+ // Otherwise, adds an onClick handler.
+ // @param [SaaSPulse SDR Tracker] the tracker instance; optional, defaults to window.tracker
+ // @return [jQuery node list] the receiver, as a jQuery node list
+ instrumentTracking: function(tracker) {
+ var handler = function() { $j(this).trackEvent({ tracker: tracker }); };
+ return jQuery(this)
+ .each(function(i, node) {
+ node = jQuery(node);
+ if (node.attr('tagName').toLowerCase() === 'form') {
+ node.submit(handler);
+ } else {
+ node.click(handler);
+ }
+ });
+ },
+
+ // Send a tracking event.
+ // @param [Object] overrides, possibly containing "activity", "module",
+ // "organization", "user", and "tracker" properties; optional
+ // @return [jQuery node list] the receiver, as a jQuery node list
+ trackEvent: function(options) {
+ var self = jQuery(this);
+ options = options || {};
+ var tracker = options.tracker || window.tracker;
+ var activity = options.activity || self._lookUpSaaSPulseProperty('activity');
+ var module = options.module || self._lookUpSaaSPulseProperty('module');
+ var organization = options.organization || self._lookUpSaaSPulseProperty('organization');
+ var user = options.user || self._lookUpSaaSPulseProperty('user');
+
+ if (tracker && activity && module && organization && user) {
+ tracker.track(activity, module, organization, user);
+ }
+
+ return self;
+ }
+
+ // Finds the closest definition of the given SaaSPulse property.
+ // @api private
+ // @param [String] the SaaSPulse property name
+ // @return [String] the value
+ _lookUpSaaSPulseProperty: function(propertyName) {
+ propertyName = 'data-saas-pulse-' + propertyName;
+ return jQuery(this)
+ .closest('[' + propertyName + ']')
+ .attr(propertyName);
+ }
+
+});

0 comments on commit 381398f

Please sign in to comment.