Skip to content

Tracker

Jump to bottom
padams edited this page Oct 21, 2026 · 15 revisions

The Tracker client adds web analytics tracking to your application. It needs no credentials.

Creating a Tracker client

<?php
require_once 'owa-php-sdk/owa-autoloader.php';   // or Composer's vendor/autoload.php

$sdk = new OwaSdk\sdk( [
    'instance_url' => 'https://owa.example.com/owa/',
] );

$tracker = $sdk->createTracker();

Track before any output is sent. The tracker sets the same owa_* cookies as OWA's JavaScript tracker, so a visitor tracked by both keeps one visitor id and one session. Cookies cannot be set once output has started.

Settings

Key Default
cookie_domain the request host, www. removed see Cookie domain
session_length 1800 seconds of inactivity that end a session
trafficAttributionMode direct direct credits the latest campaign, original the first
campaignAttributionWindow 60 days a campaign touch is kept
cookie_persistence true false makes every cookie a session cookie
respect_do_not_track true see Do Not Track

Setting the siteId

The siteId is the unique id of the tracked website or application in OWA. Every event needs one. Add sites in OWA under Administration > Sites, with the Sites client, or with the CLI; see the OWA Server wiki.

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

Setting page attributes

The page title can be any string, but usually matches the page's HTML <title>.

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

Page type groups pages in OWA's reports. It can be any string; choose names with the groupings you want in mind.

$tracker->setPageType( 'article' );

The page URL defaults to the current request's URL.

Setting user attributes

If your application signs users in, you can attach their user name and email address:

$tracker->setUserName( 'a_user_name' );
$tracker->setUserEmail( 'user@example.com' );

Custom variables

Up to five custom variables can be attached to tracking requests.

$tracker->setCustomVar( $slot, $name, $value, $scope );
Param Type
slot int Required. 1-5
name string Required.
value string Required.
scope string page (the default): this page only. session: every event in the current visit. visitor: every event from this visitor, in future visits too

name=value may be at most 65 characters; a longer pair is not set. When a slot is set in more than one scope, the narrowest wins.

getCustomVar( $slot ) reads a slot, and deleteCustomVar( $slot ) clears it in every scope.

The visitor's IP address and user agent

OWA Server reads the IP address, user agent and language from the HTTP request it receives, never from event data. The tracker forwards the visitor's as request headers:

Header Sent from
User-Agent setUserAgent(), else the visitor's User-Agent
X-Forwarded-For setIpAddress(), else the incoming X-Forwarded-For chain plus REMOTE_ADDR
Accept-Language the visitor's Accept-Language

OWA uses the leftmost public address in X-Forwarded-For. A visitor can put any address there, as they can when the JavaScript tracker reports to OWA directly. If your application runs behind a proxy and knows the real client address, pass it:

$tracker->setIpAddress( $trustedClientIp );

Geolocation

OWA resolves location from that IP address. Turn on the MaxMind GeoIP module in OWA under Administration > Modules. The SDK needs no configuration.

Cookie domain and sub domain tracking

On a host that starts with www. (www.example.com), the tracker strips www. and sets its cookies on example.com. On any other host (shop.example.com), it uses the full host.

To use another domain, for example one shared by several sub domains, set it explicitly. An explicit domain is used as given, www. included.

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

The cookie_domain setting does the same at creation.

Tracking the page view

Once the siteId and any page attributes are set:

$ok = $tracker->trackPageView();

Every tracking method returns true when OWA Server received the request, and false when it was not sent (no siteId, or Do Not Track) or failed. After a failed request, $tracker->getLastErrors() says why. OWA answers before it processes an event, so true confirms receipt, not that the event was stored.

Tracking actions

Actions track things users do: completing a form, clicking a control, printing a page. They are reported separately from page views, with their own metrics and dimensions.

$tracker->trackAction( $action_name, $action_group, $action_label, $numeric_value );
Param Type
action_name string Required. Each distinct name is a distinct type of action, for example "Recipe Print"
action_group string Groups actions in reports, for example "Cooking"
action_label string Adds detail, for example which recipe was printed: "Italian Chicken Soup"
numeric_value int or float Summed in reports 
$tracker->trackAction( 'Recipe Print', 'Cooking', 'Italian Chicken Soup' );

// with a numeric value
$tracker->trackAction( 'Recipe Print', 'Cooking', 'Italian Chicken Soup', 10 );

Tracking syndication feeds

$tracker->trackSyndicationFeed( 'rss', $subscription_id );

Tracking e-commerce transactions

  1. Describe the transaction with addTransaction(): its order id, total, tax and shipping.
  2. Add its line items with addTransactionLineItem(). Each one is a row on the invoice: a product, its unit price and the quantity ordered. Line items are tied to their transaction by the order id.
  3. Send the transaction and its line items with trackTransaction().
$tracker->setSiteId( '67b3053d792527f6b62e55b20453ad2c' );
$tracker->setPageTitle( 'Thank you' );
$tracker->trackPageView();

$order_id = 'xyz321';

$tracker->addTransaction(
    $order_id,          // the order id from your shopping cart
    'My Online Store',  // the source of the transaction, often the store's name
    '100.23',           // total revenue
    '20.20',            // total tax
    '15.30',            // total shipping
    'paypal',           // the payment gateway
    'US',               // billing country
    'NY',               // billing state
    'New York'          // billing city
);

// once per product
$tracker->addTransactionLineItem(
    $order_id,          // the parent transaction's order id
    'sku123',           // the product's SKU
    'My Product Name',
    'My Category',
    '14.95',            // unit price
    '10'                // quantity
);

$tracker->trackTransaction();

Amounts may be strings, ints or floats.

Tracking delayed transactions

Some payment providers confirm a payment after the visitor has left, for example PayPal IPN. To attribute such a transaction to the visit that placed the order, store two values while the visitor is on your site:

  • their OWA session id, from $tracker->getSessionId()
  • the full URL of the page where they placed the order

Pass both to addTransaction() when the confirmation arrives:

$tracker->setSiteId( '67b3053d792527f6b62e55b20453ad2c' );

$tracker->addTransaction(
    '12345',
    'My Online Store',
    '100.23',
    '20.20',
    '15.30',
    'paypal',
    'US',
    'NY',
    'New York',
    'https://example.com/checkout/thank-you',   // the stored page URL
    $stored_session_id                          // the stored session id
);

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

A transaction with a session id is sent without the current request's cookies, IP address or user agent: they belong to the payment provider, not the visitor. To record the visitor's, store them with the session id and set them before tracking:

$tracker->setIpAddress( $stored_ip );
$tracker->setUserAgent( $stored_user_agent );

Do Not Track

Like OWA's JavaScript tracker, the SDK does not track a browser that sends DNT: 1; tracking methods return false. To track regardless:

$tracker = $sdk->createTracker( [ 'respect_do_not_track' => false ] );

Clone this wiki locally