CommonWeb's solution is to have you specify explicitly when to work around this scenario; i.e. to
tell CommonWeb what links / forms are going to unload the page. In that case CommonWeb will prevent the default
browser action, record the event with the backend, and then re-initiate the action.

The methods that alter default behavior. Here they are:

+ `trackClicks`
+ `trackFormSubmissions`

These methods are more passive, and don't interrupt any normal event flow:

+ `trackClicksPassive`
+ `trackInputChanges`
+ `trackFormSubmissionsPassive` (coming soon)

### Specify HTML Elements (Recommended)

If you only want certain elements tracked, pass them in as the first argument to the track methods:

```javascript
// track clicks on the nav
CommonWeb.trackClicks($(".nav a"));

// track clicks with a specific attribute
CommonWeb.trackClicks($("a[data-track=true]"));

// track changes to number inputs
CommonWeb.trackInputChanges($("input[type='number']"));
```

The same arguments work for tracking non-link-clicks and forms:

```javascript
CommonWeb.trackClicksPassive($("span.less"));
CommonWeb.trackFormSubmissions($("form"));
```

##### Words of Caution

CommonWeb is designed to make tracking automatic, but the design is also aware that
tracking certain elements may not be desired, or worse, may cause unexpected behavior.

That's why, at least for now, explicitly passing the elements you care about is preferred
over grabbing everything.

And be careful not to wire up the same element twice!

### Specify Additional Properties

The default data model used to represent events is described in another section below. Sometimes you may
need to include more properties. For example, maybe you need to include extra user properties that allow for
further segmenting analysis down the road.

This can be done at a global level or for specific elements passed into `track` calls.

Here's how to add global properties that will be merged into each captured event on the page:

``` javascript
CommonWeb.addGlobalProperties({
experiment: {
id: 13983,
variant: "A"
}
});
```

Here's how to specific properties that will only be added to a specific element's click:

```javascript
CommonWeb.trackClicks($("span.less"), { another: "property" });
```

You can also pass a function to compute properties lazily at the time of the event:

```javascript
CommonWeb.trackClicksPassive($("span.even-more-stuff"), function (event, element) {
return {
event: { clientX : event.clientX },
element: { tagNameAgain : element.tagName }
};
});
```

### Custom Backend

Eventually multiple backends will be supported, but for now a Backend is just a function and you
can specify your own just like this:

```javascript
CommonWeb.Callback = function(collection, properties, callback) {
// do something with the event here!
};
```

### Data Model - Event Types

CommonWeb identifies several event types based on the interaction
- `pageviews`, `clicks`, `form-submissions`. The event type is added to the JSON
payload that represents each event so it can be used in analysis.

### Data Model - Event Properties

##### Global

These properties are sent with every event by default:

+ `page_url` - The `window.location.href` of the current page
+ `referrer_url` - The `document.referrer` of the current page

##### Events and Elements

JavaScript event and HTML element objects are turned into JSON structures and
places at the `event` and `element` top level keys respectively.

##### Session Tracking

You can have CommonWeb generate a user-specific GUID that will be sent along with all of your CommonWeb events. This GUID will be stored in the user's cookies (and persist for one year), so you can relate future events to the same user. Turn on session tracking like this:

```javascript
CommonWeb.trackSession();
```

`trackSession` will also accept two arguments: the first is the name of the cookie to use. The second is the GUID to use, if there isn't already one stored. Pass them in like this:

```javascript
CommonWeb.trackSession('custom_guid_cookie', 'semi-random-user-identifier');
```

##### Keen Backend

*More documentation needed here*

Here's an example `clicks` event that shows what properties are collected:

``` json
[
{
"parsed_user_agent": {
"device": {
"family": "Other"
},
"os": {
"major": "10",
"patch_minor": null,
"minor": "9",
"family": "Mac OS X",
"patch": "3"
},
"browser": {
"major": "36",
"minor": "0",
"family": "Chrome",
"patch": "1985"
}
},
"referrer_info": {
"medium" : "SEARCH",
"source" : "http://google.com/",
"term" : "analytics"
},
"parsed_page_url": {
"path": "/docs/data-collection",
"domain": "keen.io",
"protocol": "https",
"anchor": null,
"query_string": {
"page": "1",
"term": "analytics"
}
},
"element": {
"style": "color: blue",
"text": "Data Enrichment",
"id": "link-0",
"href": "/docs",
"tagName": "A",
"path": "html > body > p > a#link-0.classy.classy2.classy3",
"classes": [
"classy",
"classy2",
"classy3"
],
"class": "classy classy2 classy3"
},
"keen": {
"timestamp": "2014-08-12T09:19:28.605Z",
"created_at": "2014-08-12T09:19:28.605Z",
"id": "53e9dc20c9e163024bc2c799"
},
"referrer_url": "",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/36.0.1985.125 Safari/537.36",
"ip_geo_info": {
"province": "California",
"city": "San Francisco",
"postal_code": "94103",
"continent": "North America",
"country": "United States"
},
"ip_address": "199.247.206.130",
"event": {
"metaKey": false,
"type": "click"
},
"page_url": "https://keen.io/docs/data-collection",
"guid": "e54029e7-6a54-b39f-c592-022686afb9c9"
}
]
```

### Further Documentation and Examples

##### Example Page w/ Keen IO Backend

Open `index.html` after cloning this project and head to the console.
It will prompt you first to fill out Keen IO project information so that
there's somewhere to capture your events. The annoying pop-ups will go away
once you've put that in. It's there so that you don't have to hand edit the file
and then accidentally end up checking your credentials in.

The example page shows you a variety of elements. You can click on each and see
the event generated by viewing the JavaScript console.

### Contributing

**Setup**

CommonWeb uses [Gulp](http://gulpjs.com/) for building, so you will need to have [Node.js](http://nodejs.org/) installed. You can get up and running with the standard [`npm`](https://www.npmjs.com/) flow:

```
npm install
```

If you don't already have Gulp installed, you will need to install that globally.

```
npm install --global gulp
```

**Building**

You can build by calling the `build` Gulp task.

```
gulp build
```

You can also setup automatica rebuilds whenever a file changes by starting a `watch`. This can either be done directly with Gulp, or with the npm hook.

```
gulp

# or

npm start
```

##### Wishlist

+ Tests
+ Timeout and continue if a backend takes too long
+ Session ID and session age properties
+ Capture even more common interactions (e.g. time on page)
+ Create dashboards and visualizations based on this data!
+ AJAX Form Handling

## License