Skip to content

Commit

Permalink
refs matomo-org/matomo#9129 Documented tracking for Custom Dimensions
Browse files Browse the repository at this point in the history
tsteur committed Dec 7, 2015

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
1 parent e181053 commit 319f6c4
Showing 3 changed files with 51 additions and 3 deletions.
3 changes: 2 additions & 1 deletion docs/tracking-api.md
Original file line number Diff line number Diff line change
@@ -47,7 +47,7 @@ _(We recommend that these parameters be used if the information is available and
* `uid` — defines the [User ID](http://piwik.org/docs/user-id/) for this request. User ID is any non empty unique string identifying the user (such as an email address or a username). To access this value, users must be logged-in in your system so you can fetch this user ID from your system, and pass it to Piwik. The User ID appears in the visitor log, the Visitor profile, and you can [Segment](http://developer.piwik.org/api-reference/segmentation) reports for one or several User ID (`userId` segment). When specified, the User ID will be "enforced". This means that if there is no recent visit with this User ID, a new one will be created. If a visit is found in the last 30 minutes with your specified User ID, then the new action will be recorded to this existing visit.
* `cid` — defines the visitor ID for this request. You must set this value to exactly a 16 character hexadecimal string (containing only characters 01234567890abcdefABCDEF). We recommended to set the User ID via `uid` rather than use this `cid`.
* `new_visit` — If set to 1, will force a new visit to be created for this action. This feature is also [available in Javascript](http://piwik.org/faq/how-to/#faq_187).

* `dimension[0-999]` — A Custom Dimension value for a specific Custom Dimension ID (requires Piwik 2.15.1 + [Custom Dimensions plugin](https://plugins.piwik.org/CustomDimensions) see the [Custom Dimensions guide](https://piwik.org/docs/custom-dimensions/)). If Custom Dimension ID is `2` use `dimension2=dimensionValue` to send a value for this dimension. The configured Custom Dimension has to be in scope "Visit".

#### Optional Action info (measure Page view, Outlink, Download, Site search)

@@ -61,6 +61,7 @@ _(We recommend that these parameters be used if the information is available and
* `revenue` — A monetary value that was generated as revenue by this goal conversion. Only used if **idgoal** is specified in the request.
* `gt_ms` — The amount of time it took the server to generate this action, in milliseconds. This value is used to process the [Page speed report](http://piwik.org/docs/page-speed/) **Avg. generation time** column in the Page URL and Page Title reports, as well as a site wide running average of the speed of your server. _Note: when using the Javascript tracker this value is set to the ime for server to generate response + the time for client to download response._
* `cs` — The charset of the page being tracked. Specify the charset if the data you send to Piwik is encoded in a different character set than the default `utf-8`.
* `dimension[0-999]` — A Custom Dimension value for a specific Custom Dimension ID (requires Piwik 2.15.1 + [Custom Dimensions plugin](https://plugins.piwik.org/CustomDimensions) see the [Custom Dimensions guide](https://piwik.org/docs/custom-dimensions/)). If Custom Dimension ID is `2` use `dimension2=dimensionValue` to send a value for this dimension. The configured Custom Dimension has to be in scope "Action".

#### Optional [Event Tracking](http://piwik.org/docs/event-tracking/) info
* `e_c` — The event category. Must not be empty. (eg. Videos, Music, Games...)
44 changes: 44 additions & 0 deletions docs/tracking-javascript-guide.md
Original file line number Diff line number Diff line change
@@ -278,6 +278,50 @@ _paq.push([ function() {
_paq.push(['trackPageView']);
```
## Custom Dimensions
[Custom Dimensions](https://piwik.org/docs/custom-dimensions/) are a powerful feature that enable you to track custom values for each visit, and/or each action (page view, outlink, download). This feature is not shipped with Piwik directly but can be installed as a plugin via the [Piwik Marketplace (CustomDimensions plugin)](https://plugins.piwik.org/CustomDimensions). Before you can use a Custom Dimension you need to install the plugin and configure at least one dimension, see the [Custom Dimensions guide](https://piwik.org/docs/custom-dimensions/). You will get a numeric ID for each configured Custom Dimension which can be used to set a value for it.
### Tracking a Custom Dimension across tracking requests
To track a value simply specify the ID followed by a value:
```javascript
_paq.push(['setCustomDimension', customDimensionId = 1, customDimensionValue = 'Member']);
```
Please note once a Custom Dimension is set, the value will be used for all following tracking requests and may lead to
inaccurate results if this is not wanted. For example if you track a page view, the Custom Dimension value will be as well tracked for each following event, outlink, download, etc. within the same page load. To delete a Custom Dimension value after a tracking request call
`_paq.push(['deleteCustomDimension', customDimensionId]);`
### Tracking a Custom Dimension for one specific action only
It is possible to set a Custom Dimension for one specific action only. If you want to track a Page view, you can send one or more specific Custom Dimension values along with this tracking request as follows:
`_paq.push(['trackPageView', pageTitle, {dimension1: 'DimensionValue'}]);`
To define a dimension value pass an object defining one or multiple properties as the last parameter. The property name for a dimension starts with `dimension` followed by a Custom Dimension ID, for example `dimension1`. The same behaviour applies for several other methods:
```javascript
_paq.push(['trackEvent', category, action, name, value, {dimension1: 'DimensionValue'}]);
_paq.push(['trackSiteSearch', keyword, category, resultsCount, {dimension1: 'DimensionValue'}]);
_paq.push(['trackLink', url, linkType, {dimension1: 'DimensionValue'}]);
_paq.push(['trackGoal', idGoal, customRevenue, {dimension1: 'DimensionValue'}]);
```
The advantage is that the set dimension value will be only used for this particular action and you do not have to delete the value after a tracking request. You may set multiple dimension values like this:
`_paq.push(['trackPageView', pageTitle, {dimension1: 'DimensionValue', dimension4: 'Test', dimension7: 'Value'}]);`
### Retrieving a Custom Dimension value
```javascript
getCustomDimension(customDimensionId)
```
This function can be used to get the value of a Custom Dimension. It will only work if a Custom Dimension was set during the same page load.
## User ID
[User ID](http://piwik.org/docs/user-id/) is a feature in Piwik that lets you connect together a given user's data collected from multiple devices and multiple browsers. There are two steps to implementing User ID:
7 changes: 5 additions & 2 deletions docs/tracking-javascript.md
Original file line number Diff line number Diff line change
@@ -71,9 +71,12 @@ Read also the **[Javascript Tracking Client](/guides/tracking-javascript-guide)*
* `getUserId()` - returns the User ID string if it was set.
* `setUserId( userId )` - Sets a [User ID](http://piwik.org/docs/user-id/) to this user (such as an email address or a username).
* `setCustomVariable (index, name, value, scope)` - Set a custom variable.
* `deleteCustomVariable (index, scope )` - Delete a custom variable.
* `getCustomVariable (index, scope )` - Retrieve a custom variable.
* `deleteCustomVariable (index, scope)` - Delete a custom variable.
* `getCustomVariable (index, scope)` - Retrieve a custom variable.
* `storeCustomVariablesInCookie()` - When called then the Custom Variables of scope "visit" will be stored (persisted) in a first party cookie for the duration of the visit. This is useful if you want to call `getCustomVariable` later in the visit. (by default custom variables are not stored on the visitor's computer.)
* `setCustomDimension (customDimensionId, customDimensionValue)` - Set a custom dimension. (requires Piwik 2.15.1 + [Custom Dimensions plugin](https://plugins.piwik.org/CustomDimensions))
* `deleteCustomDimension (customDimensionId)` - Delete a custom dimension. (requires Piwik 2.15.1 + [Custom Dimensions plugin](https://plugins.piwik.org/CustomDimensions))
* `getCustomDimension (customDimensionId)` - Retrieve a custom dimension. (requires Piwik 2.15.1 + [Custom Dimensions plugin](https://plugins.piwik.org/CustomDimensions))
* `setCampaignNameKey(name)` - Set campaign name parameter(s). (Help: [Customize Campaign name parameter names](http://piwik.org/faq/how-to/#faq_120))
* `setCampaignKeywordKey(keyword)` - Set campaign keyword parameter(s). (Help: [Customize Campaign keyword parameter names](http://piwik.org/faq/how-to/#faq_120))
* `setConversionAttributionFirstReferrer( bool )` - Set to true to attribute a conversion to the first referrer. By default, conversion is attributed to the most recent referrer.

0 comments on commit 319f6c4

Please sign in to comment.