README

A server-side Google Analytics tracking helper for CraftCMS

A Top Shelf Craft creation
Michael Rog, Proprietor

Tracker provides a helper method for sending Google Analtyics tracker hits programatically from CraftCMS templates or services.

Installation

1. From your project directory, use Composer to require the plugin package:

   composer require topshelfcraft/tracker
   

2. In the Control Panel, go to Settings → Plugins and click the “Install” button for Tracker.

3. There is no Step 3.

(Tracker is also available for installation via the Craft CMS Plugin Store.)

Usage

To track a page view:

{% set params = {
	trackingId: 'UA-12345-67',
	location: 'http://myawesomesite.com/foo.html',
	title: 'My Page Title'
} %}

{% do craft.tracker.track(params) %}

To track an event:

{% set params = {
	trackingId: 'UA-12345-67',
	location: 'http://myawesomesite.com/foo.html',
	type: 'event',
	eventCategory: 'Music Player',
	eventAction: 'Play button',
	eventLabel: 'The Beatles - Yesterday',
	eventValue: '1461603558'
} %}

{% do craft.tracker.track(params) %}

From PHP, using the Helper class:

use topshelfcraft\tracker\Tracker;

$params = [
    'location' => Craft::$app->request->getUrl(),
    'clientId' => $currentUserId,
    'type' => 'pageview',
    'trackingId' => $trackingId,
    'version' => '1',
];

Tracker::getInstance()->track($params);

Parameters listing

Here's a handy cheat-sheet of all the parameters Google Analytics may accept with tracker hits:

• https://www.cheatography.com/dmpg-tom/cheat-sheets/google-universal-analytics-url-collect-parameters/

The parameter names aren't very friendly, so the Tracker plugin gives you a friendlier set of handles to use, which will be mapped to the official API parameter handles when the request is instantiated:

The full map is defined in the GoogleParamNames constant in Settings.php:

/*
 * Main Parameters
 */

'adSenseNumber' => 'a', // Random number used to link Google Analytics to Adsense (currently not working)
'clientId' => 'cid', // Client ID number
'encodingType' => 'de', // Document Encoding type
'location'  => 'dl', // URL of the page being viewed.
'title' => 'dt', // Page title of the page being viewed.
'flashVersion' => 'fl', // Flash version on the site.
'nonInteraction' => 'ni', // Non-interaction hit type (1 = yes, 0 = no)
'javaEnabled' => 'je' , // Whether Java is enabled on the site, (1 = yes, 2 = no)
'screenDepth' => 'sd', // The view screen's depth.
'screenResolution' => 'sr', // The view screen's resolution.
'type' => 't', // The Type of tracking call that triggers the analytics request (e.g. pageview, event).
'trackingId' => 'tid', // Google Analytics user account number (UA-XXXXXX-X)
'userLanguage' => 'ul', // Language displayed on the site.
'version' => 'v', // Protocol version
'sdkVersion' => '_v', // SDK version number.
'hitIncrement' => '_s', // Hit Sequence, increments each time an event happens.
'verificationCode' => '_u', // Verification code generated by GA analytics.js
'cacheBuster' => 'z', // Functions as a cachebuster.

/*
 * Override Parameter
 */

'documentHostNameOverride' => 'dh', // Document host name override
'documentPathOverride' => 'dp', // Document Path override, used when overriding the standard page name.
'userAgentOverride' => 'ua', // User agent override.
'userIpOverride' => 'uip', // User Ip override.
'screenName' => 'cd', // Screen name, mainly used in app tracking.
'linkId' => 'linkid', // Link ID of a clicked DOM element.

/*
 * Events Parameters
 *
 * You will only see any of these when t (type) = event
 */

'eventAction' => 'ea', // Event Action.
'eventCategory' => 'ec', // Event Category.
'eventLabel' => 'el', // Event Label.
'eventValue' => 'ev', // Event value.

/*
 * Timing Parameters
 */

'userTimingCategory' => 'utc', // User timing category, not universal coordinated time.
'userTimingVarName' => 'utv', // User timing variable name.
'userTimingTime' => 'utt', // User timing time.
'userTimingLabel'=> 'utl', // User timing label.
'pageLoadTime' => 'plt', // Page load time.
'dnsTime' => 'dns', // DNS time.
'pageDownloadTime' => 'pdt', // Page download time.
'redirectResponseTime' => 'rrt', // Redirect response time.
'tcpConnectTime' => 'tcp', // TCP connect time.
'serverResponseTime' => 'srt', // Server response time.
'exceptionDescription' => 'exd', // Exception Description.
'isExceptionFatal' => 'exf', // Whether exception fatal or not.

/*
 * Campaign Variable Parameters
 *
 * To register any campaign variables (c*) you MUST populate Campaign Source AND Campaign Medium as a minimum.
 */

'campaignName' => 'cn', // Campaign name.
'campaignSource' => 'cs', // Campaign source.
'campaignMedium' => 'cm', // Campaign medium.
'campaignKeyword' => 'ck', // Campaign keyword.
'campaignContent' => 'cc', // Campaign content.
'campaignId' => 'ci', // Campaign Id.
'adwordsId' => 'glcid', // Google adwords id.
'displayAdsId' => 'dclid', // Google display ads id.

/*
 * eCommerce Parameters
 *
 * You will only see these when t (Type) = transaction or item.
 */

'currency' => 'cu', // Currency the transaction takes place in.
'itemName' => 'in', // The item name.
'itemCode' => 'ic', // The item's sku.
'itemPrice' => 'ip', // The item's price (per unit).
'itemQuantity' => 'iq', // Item quantity.
'itemVariation' => 'iv', // The item's category or variety.
'transactionAffiliation' => 'ta', // The transaction affiliation.
'transactionIdentification' => 'ti', // Transaction identification number.
'transactionRevenueValue' => 'tr', // Transactions' revenue value.
'transactionShippingValue' => 'ts', // Transactions' shipping value.
'transactionTaxValue' => 'tv', // Transaction tax value.

/*
 * App Tracking Parameters
 */

'applicationId' => 'aid', // Application Id.
'applicationInstallerId' => 'aiid', // Application installer Id.
'applicationName' => 'an', // Application Name.
'applicationVersion' => 'av', // Application version.
'hitSequence' => 'ht', // Hit sequence.

/*
 * Other Parameters
 *
 * When using 'anonymizeIp' the key just needs to be there, you can pass it any value, or pass it no value and
 * and it will anonymize the IP.
 */

'anonymizeIp' => 'aip', // Anonymize IP address.
'queueTime' => 'qt', // Queue time ( for collecting offline data).
'sessionControl' => 'sc', // Session Control.
'userId' => 'uid', // User ID (known uid as opposed to cid).

/*
 * Google Experiments Parameters
 */

'experimentId' => 'xid', // The experiment id.
'experimentVariant' => 'xvar', // The experiment variant.

/*
 * Social Tracking Parameters
 */

'socialNetwork' => 'sn', // The social network.
'socialAction' => 'sa', // Social action.
'socialActionTarget' => 'st', // The social action target, typically a URL.

);

Configuration

The Tracker plugin config file allows you to set the default Tracking ID, as well as to provide default parameters for the site and/or environment:

// (in tracker.php config file)

return [
	'trackingId' => 'UA-XXXXXX-XX',
	'defaultParams' => [],
];

Any default parameters you provide will be added to each request, before the user-provided parameters are added from the method call.

What are the system requirements?

Craft 3.0+

I found a bug.

Please open a GitHub Issue, or if you're feeling generous, submit a PR to the 3.x.dev branch.

Contributors:

• Plugin development: Michael Rog / @michaelrog
• Plugin development: Tyler Neustaedter
• Development assistance: Aaron Waldon / @causingeffect
• Plugin icon: Pantelis Gkavos (via The Noun Project)