Tracker

The Tracker client can be used to add web analytics tracking functions to your application.

Creating a Tracker Client

<?php require_once('owa-php-sdk/owa-autoloader.php');

$config = [
    'instance_url' => 'http://your.domain.com/owa/'
];

$sdk = new OwaSdk\sdk($config);
$tracker = $sdk->createTracker();
?>

Setting the siteId

the siteID is the unique ID of the tracked website/application in OWA. A siteID is required in order to ensure that tracking events associated with the proper tracked website. Tracked websites can be added to your OWA Instance via the admin interface (Settings > Sites), the REST API, or the CLI. See the OWA Core wiki.

To set the siteID in the tracker:

$tracker->setSiteId('your-siteId');

Setting Page Attributes

You can set various page attributes including the page title and page type. Page title can be whatever string you want but generally should correspond to the HTML <title> tag of the page being tracked.

$tracker->setPageTitle('Your Page Title');

Page type is a dimension used to rollup groups of pages in OWA reporting. It can be whatever string you want but some forethought should be given to how to want to group pages.

$tracker->setPageType('your_page_type');

Setting User Attributes

If your website or application authenticates users in some way you can set various attributes about them including user name and email address.

$tracker->setUserName("a_user_name");

$tracker->setUserEmail("a_user_name");

Setting Custom Variables

Up to five custom variables can be set and appending to all tracking requests. Custom variables can set for a single page or persisted and set on all requests made in the current and/or future visits.

$tracker->setCustomVar( $slot, $name, $value, $scope );

Parameters

Param	Type	Description
slot	integer	Required. The variable slot to set. Currently OWA supports 1-5.
name	string	Required. The name portion of the variable.
value	string	Required. The value portion of the variable.
scope	string	Required. The scope of the variable. Allowed values include: page

Cookie Domain and Sub Domain Tracking

When the tracker s used to track 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 setCookieDomain method.

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 method and passing the domain that you want to use.

$tracker->setCookieDomain('somedomain.com');

Tracking the Page View

Once the siteId and any page attributes are set you are ready to track the page view.

$tracker->trackPageView();

Tracking Actions

Action Tracking provides a way to track actions that users perform on your website. An action could anything ranging from the completion of a web form to clicking on a particular link or UI control.

Actions are reported separately from pages views and have their own metrics & dimensions in OWA reporting.

The trackAction method issued to track an action.

$tracker->trackAction( $action_name, $action_group, $action_label, $numeric_value);

Properties

Actions have a few properties that you can set during tracking.

Param	Type	Description
Name	string	Actions can be given any name you want. Each unique action name will result in a unique type of action. For example let's pretend that we have a an action called "Recipe Print" which would be triggered whenever a users clicked on the print icon on one of our pretend recipe web pages.
Group	string	It is possible to group actions for purposes of reporting. It might be helpful to group on "Recipe Print" action under the action group called "Cooking".
Label	string	optional. Sometimes just looking at actions by name or group is does not provide enough detail. That's where labels come in. For example, let's say that we wanted to see which recipe's were being printed. To accomplish this we could assign a label to the action. In this case the label could be the name title of the recipe, say "Italian Chicken Soup".
Numeric Value	integer	optional. Actions can have a numeric value associated with them. This value will display summarized in reporting.

###Examples

$tracker->trackAction('Cooking', 'Recipe Print', 'Italian Chicken Soup');

Action with a numeric value:

$tracker->trackAction('Cooking', 'Recipe Print', 'Italian Chicken Soup', 10);