Collecting data with Trackers and Webhooks

  1. Home
  2. Docs
  3. Collecting data with Trackers and Webhooks
  4. Trackers – collecting data from your own applications
  5. PHP tracker
  6. Tracking an event

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 manually override the timestamp attached to this event. The timestamp should be in milliseconds since the Unix epoch.

If you do not pass this timestamp in as an argument, then the PHP Tracker will use the current time to be the timestamp for the event.

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, $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 transactionYesArray
$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 datadata 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).