Skip to main content

Tracking an event

Tracking methods supported by the PHP Tracker:

FunctionDescription
trackPageViewTrack and record views of web pages.
trackEcommerceTransactionTrack an ecommerce transaction
trackScreenViewTrack the user viewing a screen within the application
trackStructEventTrack a Snowplow custom structured event
trackUnstructEventTrack a Snowplow custom unstructured event

Optional Tracking Arguments‚Äč

Custom Context‚Äč

Custom contexts let you add additional information about any circumstances surrounding an event in the form of a PHP Array of name-value pairs. Each tracking method accepts an additional optional contexts parameter after all the parameters specific to that method:

public function trackPageView($page_url, $page_title = NULL, $referrer = NULL, $context = NULL, $tstamp = NULL)

An example of a Context Array Structure:

array(
"schema" => "iglu:com.acme_company/movie_poster/jsonschema/2-1-1",
"data" => array(
"movie_name" => "Solaris",
"poster_country" => "JP"
)
)

This is how to fire a page view event with the above custom context:

$tracker->trackPageView(
"http://www.films.com",
"Homepage",
NULL,
array(
array(
"schema" => "iglu:com.acme_company/movie_poster/jsonschema/2-1-1",
"data" => array(
"movie_name" => "Solaris",
"poster_country" => "JP"
)
)
)
);

Timestamp‚Äč

Each tracking method supports an optional timestamp as its final argument; this allows you to also set the true timestamp (true_tstamp) of the event besides the device created timestamp (dvce_created_tstamp) that always gets set by the tracker. The optional timestamp argument should be provided in milliseconds since the Unix epoch.

Here is an example tracking a structured event and supplying the optional timestamp argument. We can explicitly supply a NULL for the intervening arguments which are empty:

$tracker->trackStructEvent("some cat", "save action", NULL, NULL, NULL, 1368725287000);

Event Tracking Methods‚Äč

trackPageView‚Äč

Track a user viewing a page within your app.

Function:

public function trackPageView($page_url, $page_title = NULL, $referrer = NULL, $context = NULL, $tstamp = NULL)

Arguments:

ArgumentDescriptionRequired?Validation
$page_urlThe URL of the pageYesNon-empty string
$page_titleThe title of the pageNoString
$referrerThe address which linked to the pageNoString
$contextCustom context for the eventNoArray
$tstampWhen the pageview occurredNoPositive integer

Example Usage:

$tracker->trackPageView("www.example.com", NULL, NULL, NULL, 123123132132);

trackEcommerceTransaction‚Äč

Track an ecommerce transaction.

Function:

public function trackEcommerceTransaction($order_id, $total_value, $currency = NULL, $affiliation = NULL, $tax_value = NULL, $shipping = NULL, $city = NULL, $state = NULL, $country = NULL, $items = array(), $context = NULL, $tstamp = NULL)

Arguments:

ArgumentDescriptionRequired?Validation
$order_idID of the eCommerce transactionYesNon-empty string
$total_valueTotal transaction valueYesInt or Float
$currencyTransaction currencyNoString
$affiliationTransaction affiliationNoString
$tax_valueTransaction tax valueNoInt or Float
$shippingDelivery cost chargedNoInt or Float
$cityDelivery address cityNoString
$stateDelivery address stateNoString
$countryDelivery address countryNoString
$itemsItems in the transactionNoArray
$contextCustom context for the eventNoArray
$tstampWhen the transaction event occurredNoPositive integer

Example Usage:


$tracker->trackEcommerceTransaction(
"test_order_id_1",
200,
"GBP",
"affiliation_1",
"tax_value_1",
"shipping_1",
"city_1",
"state_1",
"country_1",
array(
array("name" => "name_1","category" => "category_1",
"price" => 100,"sku" => "sku_1","quantity" => 1),
array("name" => "name_2","category" => "category_2",
"price" => 100,"sku" => "sku_2","quantity" => 1)
)
);

The above example contains an order with two order items.

trackEcommerceTransactionItem‚Äč

This is a private function that is called from within trackEcommerceTransaction. Note that for an item to be added successfully you need to include the following fields in the array, even if the value is NULL.

Arguments:

ArgumentDescriptionRequired?Validation
"sku"Item SKUYesNon-empty string
"price"Item priceYesInt or Float
"quantity"Item quantityYesInt
"name"Item nameNoString
"category"Item categoryNoString

Example Item:

array(
array("name" => NULL,
"category" => NULL,
"price" => 100,
"sku" => "sku_1",
"quantity" => 1)
)

If any of these fields are missing the item event will not be created. However the order of these fields is not important.

trackScreenView‚Äč

Track a user viewing a screen (or equivalent) within your app.

Function:

public function trackScreenView($name = NULL, $id = NULL, $context = NULL, $tstamp = NULL)

Arguments:

ArgumentDescriptionRequired?Validation
$nameHuman-readable name for this screenNoNon-empty string
$idUnique identifier for this screenNoString
$contextCustom context for the eventNoArray
$tstampWhen the screen was viewedNoPositive integer

Although $name and $id are not individually required, at least one must be provided or the event will fail validation.

Example:

$tracker->trackScreenView("HUD > Save Game", NULL, NULL, 1368725287000);

trackStructEvent‚Äč

Track a custom event happening in your app which fits the Google Analytics-style structure of having up to five fields (with only the first two required).

Function:

public function trackStructEvent($category, $action, $label = NULL, $property = NULL, $value = NULL, $context = NULL, $tstamp = NULL)

Arguments:

ArgumentDescriptionRequired?Validation
$categoryThe grouping of structured events which this action belongs toYesNon-empty string
$actionDefines the type of user interaction which this event involvesYesNon-empty string
$labelA string to provide additional dimensions to the event dataNoString
$propertyA string describing the object or the action performed on itNoString
$valueA value to provide numerical data about the eventNoInt or Float
$contextCustom context for the eventNoArray
$tstampWhen the structured event occurredNoPositive integer

Example:

$tracker->trackStructEvent("shop", "add-to-basket", NULL, "pcs", 2);

trackUnstructEvent‚Äč

Track a custom event which consists of a name and an unstructured set of properties. This is useful when:

  • You want to track event types which are proprietary/specific to your business (i.e. not already part of Snowplow), or
  • You want to track events which have unpredictable or frequently changing properties

Function:

public function trackUnstructEvent($event_json, $context = NULL, $tstamp = NULL)

Arguments:

ArgumentDescriptionRequired?Validation
$event_jsonThe properties of the eventYesArray
$contextCustom context for the eventNoArray
$tstampWhen the unstructured event occurredNoPositive integer

Example:

$tracker->trackUnstructEvent(
array(
"schema" => "com.example_company/save-game/jsonschema/1.0.2",
"data" => array(
"save_id" => "4321",
"level" => 23,
"difficultyLevel" => "HARD",
"dl_content" => true
)
),
NULL,
132184654684
);

The $event_json must be an array with two fields: schema and data. data is a flat array containing the properties of the unstructured event. schema identifies the JSON schema against which data should be validated.

Extra Tracker Functions‚Äč

Tracker¬†flushEmitters‚Äč

The flushEmitters function can be called after you have successfully created a Tracker with the following function call:

$tracker->flushEmitters();

This will tell the tracker to send any remaining events that are left in the buffer to the collector(s).