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);

Tracking E-Commerce Transactions

To track e-commerce transactions you must use OWA's commerce tracking methods as outlined below.

First, describe the E-commerce Transaction using the addTransaction method to tell OWA about the overall e-commerce transaction including its unique order id, the total amount, total tax, and total shipping.

Next, add "line items" to the transaction using the addTransactionLineItem method which tells OWA about the line items that make up this transaction. A good way to think of line items is as the rows on a paper invoice that describe the products being purchased, their unit prices and the quantities being ordered. Like offline transactions that might occur at a grocery store, a single e-commerce transaction can contain multiple products each of which is represented in OWA as it's own transaction line item. Line items are stored in OWA associated with their parent transaction using the ''order id'' supplied when you described the transaction.

Finally, track the Transaction using the trackTransaction method which will send the transaction and its line items to OWA Server.

Example

$tracker->setSiteId('67b3053d792527f6b62e55b20453ad2c'); // set the siteId
$tracker->SetPageTitle('My page title');
$tracker->trackPageView(); // track the page view

$order_id = xyz321;
$tracker->addTransaction(
          $order_id, // the unique order id generated by your shopping cart/commerce application
          'My Online Store', // the source of the transaction, often the name of the store 
          '100.23', // the total revenue amount. Rounded to two decimal places. 
          '20.20', // the total tax amount. Rounded to two decimal places. 
          '15.30', // the total shipping amount. Rounded to two decimal places.  
          'paypal', // the name of the transaction gateway or payment service used
);

// repeat this as many times as their are products/line items
$tracker->addTransactionLineItem(
          $order_id, // the unique order id of the parent transaction
          'sku123', // the unique  SKU id assigned o this product by your shopping cart/commerce application
          'My Product Name', // the name of the product
          'My Category', // the name of the category this product s associated to with
          '14.95', // the unit price of the product. Rounded to two decimal places.
          '10' // the quantity of the product ordered
);

// sends the transaction and line items for processing
$tracker->trackTransaction();

Tracking Delayed E-commerce Transactions

The addTransaction method contains two additional arguments that allow you to record transactions that happen asynchronously to a user's page view. This sometimes happens when a credit card provider has non-real-time card authorization (such as PayPal IPN).

To send transactions to OWA asynchronously you must store the user's OWA session id and the full URL of the "success" or "thank you" page that the user saw at the time that they performed the transaction. These two pieces of data must be included in the addTransaction method call that you make at a later time.

You can retrieve the user's session_id from the OWA session cookie using the getSessionId tracker method:

$session_id = $tracker->getSessionId();

Example

    $tracker->setSiteId('67b3053d792527f6b62e55b20453ad2c'); // set the siteId
    $tracker->addTransaction(
          '12345', // the unique order id generated by your shopping cart/commerce application
          'My Online Store', // the source of the transaction, often the name of the store 
          '100.23', // the total revenue amount. Rounded to two decimal places. 
          '20.20', // the total tax amount. Rounded to two decimal places. 
          '15.30', // the total shipping amount. Rounded to two decimal places.  
          'paypal', // the name of the transaction gateway or payment service used
          'New York',
          'NY',
          'United States'
          'http://domain.com/page/that/transaction/occured', // This is the url of the transaction page.
          'some_session_id' // The session ID of the user that you stored earlier.
    );

    $tracker->addTransactionLineItem( ... );
    $tracker->trackTransaction();