From Open Web Analytics Wiki
Adding Tracker to Your Web Page
This section discusses the code used to add the tracker to your web page. OWA will generate a customized version of this code for each site that you add to the site roster. See the Administration -> Site Roster page within OWA's management interface to get the tracking code for a particular web site and use that code as a starting place for further customizing how you want the tracker to behave.
Traditional Tracker Code
Lets consider each line one by one:
var owa_baseUrl = 'http://your.domain.com/path/to/owa/';
OWATracker = new OWA.tracker();
Sets the Id of the site that you are tracking so that this ID will be logged as part of all events recorded by the Tracker. Site IDs are generated by the OWA admin interface whenever you add a new site to track.
This line tells the tracker to track the page view and send the event to the server. If you want to pass custom event attributes (like page type, or title, etc.) be sure to set those before
trackPageViewmethod is called or else they will not make it into the event before it is sent to the server.
Async Tracker Code (v1.4.0 or later)
Lets consider each line one by one:
var owa_baseUrl = 'http://your.domain.com/path/to/owa/';
var owa_cmds = owa_cmds || ;
owa_cmds is a global variable that houses the queue of commands that you want to execute when the tracker becomes available.
This line adds a command to execute the
This is an anonymous function that will insert a
<script> tag into your web page that will download the tracker library from the server.
Tracker can be configured to track any clicks that occur on any DOM element of your web pages. This includes links, buttons, images, form elements as well as all HTML elements such as
span, div, p. Tracker will report these click events back to the server as they happen via
<img> tag requests.
To tell Tracker to track clicks just call the
trackClicks() method on your Tracker object like so:
Tracker can be configured to the stream of mouse oriented events (movement, click, focus, etc.) that a user generated while they interact with your web page and send the "dom stream" to the server as a single event. This mode is used by OWA record domstreams that can be played back by OWA's javascrpt domstream player.
To track the domstream of users call the
trackDomStream() method on your Tracker object like so:
You can adjust the percentage of time that Domstreams are recorded by setting the
logDomStreamPercentage option by calling the
setOption() method on your Tracker object like so:
The numeric value will be interpreted as a percentage.
Often time you web site will contain specific "actions" that your users can perform that need to be tracked separately of page views. This could be the submission of a web form, or the click on a particular link or element on a web page.
It is possible to track an unlimited number of custom actions using the
trackAction method. This method takes four parameters.
- string action_group required. This is the name by which you will later be able to "group" actions in your reporting (i.e. "Cooking").
- string action_name required. This is the name of the action. Unique names will count as unique actions (i.e. "Recipe Print").
- string action_label optional. This is an optional text label that can be used to further describe the action (i.e. "Best Chicken Parmesan Recipe").
- integer numeric_value optional. This is an number that you can store along with each event. This value will be summarized in reporting.
OWATracker.trackAction('Cooking', 'Recipe Print', 'Best Chicken Parmesan Recipe', 10);
The tracker contains methods for tracking e-commerce transactions the products that are purchased as part of that transaction. See ecommerce tracking for more info on how these methods work.
These methods do not perform any calculations, such as quantity,revenue, or currency calculations. Keep the following in mind when using these methods:
- You must make sure that the total amount of your transaction is equal to the sum of the implied value (unit price x quantity) of product line items that you associate with it using
- Ensure that each product you add has its own unique name and SKU.
- A refund can be represented by creating a new transaction with a with negative total and negative quantities in its associated line items.
addTransaction( order_id, order_source, total, tax, shipping, gateway, city, state, country )
Creates an e-commerce transaction object with the values passed.
- string order_id required. The unique ID assigned to the transaction by your e-commerce shopping cart application.
- string order_source optional. The store name or partner channel associated with the transaction.
- string total required. The total amount of the transaction.
- string tax optional. The amount of tax associated with the transaction.
- string shipping optional. The cost of shipping associated with the transaction.
- string gateway optional. The name of the transaction gateway or shopping cart application associated with the transaction.
- string city optional. The city associated with the transaction.
- string state optional. The state associated with the transaction.
- string country optional. The country associated with the transaction.
addTransactionLineItem( order_id, sku, product_name, category, unit_price, quantity )
Adds a product line item containing information about the product and the quantity that was purchased as part of the transaction. You can call this method repeatedly to add multiple unique product line items to the transaction, however only add a single line item for each unique product that is part of the transaction.
AddTransaction must be called prior to using this method.
- string order_id required. The unique ID assigned to the transaction by your e-commerce shopping cart application. Should be the same as the value used in the
- string SKU optional. The SKU of the product associated with the line item.
- string product_name required. The name of the product associated with the line item.
- string category optional. The category of the product associated with the line item.
- string unit_price required. The unit price of the product associated with the line item.
- string quantity required. The quantity purchased of the product associated with the line item.
This method send the e-commerce transaction and any associated product line items to the server.
Using Multiple Trackers on the Same Web Page
OWATracker = new OWA.tracker(); OWATracker2 = new OWA.tracker();
Using the async code you simply have to refer to the variable names when adding methods to the command queue. For example:
owa_cmds.push(['trackPageView']); // refers to the default tracker object called OWATracker owa_cmds.push(['OWATracker2.trackPageView']); // this will create the OWATracker2 object if it doesn't already exist and then call this trackpageView method.
Custom Event Tracking
You can use the Tracker to track custom event types that you define. Custom events should only be used when you need to track complex events and control the processing of that event on the server. If you only need ot track simple "actions" then use the Action Tracking methods instead.
The following code illustrates how to create a custom event, set an event type that your server will listen for, set an event property (name/value pair), and log it:
var myEvent = OWATracker.makeEvent(); myEvent.setEventType("someeventname"); myEvent.set("somename", "somevalue"); OWATracker.trackEvent(myEvent)
Cross Domain Tracking
Sometimes it is necessary to track the same visitor across two different web domains without that them appearing as a separate visitors on each of the domains. To accomplish this, you can tell OWA to share the contents of the visitor's OWA's cookies with the other web site that is also being tracked by OWA. There are three OWA tracker methods that enable you to do this.
This method is used to pass a visitor's OWA state via a text link to another instance of OWA running on another web domain. The method takes the full URL of the link as an argument and is typically called as an "onclick" handler. For example:
<a href="/some_page.html" onclick="OWATracker.shareStateByLink(this.href); return false;">Test Link</a>
This method is used to pass a visitor's OWA state to another web domain via a http POST operation such as a form submit. This method take the form object as an argument and is typically used as an "onsubmit" handler. For example:
<form action="http://www.someotherdomain.com/formHandler.php" name="myform" method="post" onsubmit="OWATracker.shareStateByPost( this );"> . . . </form>
This method should be added to the OWA tracker that is running under the web domain you want to share the visitor's state with. This method will look for the shared state on the URL and then use store that shared state in cookies instead of creating new state for the visitor. This has the effect of making the visitor's session appear to be in progress" to the tracker which now use the shared visitor ID, session ID etc.
Here is an example of how to call this method.
Cookie Domain and Sub Domain Tracking
When the tracker is included on a web page that is part of a sub domain (i.e. not 'www') it will automatically use the full sub domain for setting its cookies. You can alter that behavior and set an alternative higher level domain by calling the
When tracking pages under a domain that begins with "www" (i.e. "www.yourdomain.com"), OWA will automatically strip the "www" and use a higher level domain for setting it's cookies (i.e. "yourdomain.com"). You can stop this from happening by calling
setCookieDomain and passing the domain that you want to use.
setCookieDomain( domain )
Alters the domain name used when setting cookies. A leading "." will be added to all domains.
- string domain required. The full domain name to be used.
setCustomVar( slot, name, value, scope )
Sets a custom variable that will be recorded with each tracking event. Variables can set for a single page or persisted and set on all requests made in the current and/or future visits.
- int slot required. The variable slot to set. Currently OWA supports 1-5.
- string name required. The name portion of the variable.
- string value required. The value portion of the variable.
- string scope required. The scope of the variable. Allowed values include: page|session|visitor.
Adding Search Engines
You can add to list of domains that the tracker will recognize as an organic search engine source of traffic. The addOrganicSearchEngine method take a domain name (e.g. search.foo.com) as well as the url parameter that the tracker should look at in order to retrieve the query terms used in the search.
owa_cmds.push(['addOrganicSearchEngine', 'somedomain.com', 'somequerystringparam']);
This configuration method should be called before all tracking methods.
The tracker code is contained in the