Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document few changes for Matomo 4 #353

Merged
merged 2 commits into from
Jun 18, 2020
Merged

Document few changes for Matomo 4 #353

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
48de11f
Document few changes for Matomo 4
tsteur Jun 18, 2020
c0e690d
few more tweaks
tsteur Jun 18, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/4.x/ab-tests/browser.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ _paq.push(['AbTesting::create', {
}
return false;
},
matomoTracker: Matomo.getAsyncTracker(piwikUrl, piwikSiteId),
piwikTracker: Matomo.getAsyncTracker(matomoUrl, matomoSiteId),
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Guess the piwikTracker option hasn't been renamed in the plugin yet?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

exactly, will change the premium feature docs once we renamed things there

variations: [
// [...]
{
Expand Down
32 changes: 16 additions & 16 deletions docs/4.x/content-tracking.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,13 +62,13 @@ Once you have initialized the tracker you have to tag HTML blocks to declare the

The following attributes and their corresponding CSS classes are used for this and explained in detail in the next chapters:

| Selector | Description |
| ---------------------------------------------------------------------- | --------------------------------------------------- |
| `[data-track-content]` or `.piwikTrackContent` | Defines a content block |
| `[data-content-name=""]` | Defines the name of the content block |
| `[data-content-piece=""]` or `.piwikContentPiece` | Defines the content piece |
| `[data-content-target=""]` or `.piwikContentTarget` | Defines the content target |
| `[data-content-ignoreinteraction]` or `.piwikContentIgnoreInteraction` | Declares to not automatically track the interaction |
| Selector | Description |
| ----------------------------------------------------------------------- | --------------------------------------------------- |
| `[data-track-content]` or `.matomoTrackContent` | Defines a content block |
| `[data-content-name=""]` | Defines the name of the content block |
| `[data-content-piece=""]` or `.matomoContentPiece` | Defines the content piece |
| `[data-content-target=""]` or `.matomoContentTarget` | Defines the content target |
| `[data-content-ignoreinteraction]` or `.matomoContentIgnoreInteraction` | Declares to not automatically track the interaction |


You can use either **HTML attributes** or **CSS classes** to tag content.
Expand All @@ -92,7 +92,7 @@ Here we are defining a content block having the name "My Product Name". The used

#### How to define a block of content?

Defining a content block is mandatory in order to track any content. For each ad, banner or any other content you want to track you will have to create a content block. You can use either the attribute `data-track-content` or the CSS class `piwikTrackContent`. The attribute does not require any value.
Defining a content block is mandatory in order to track any content. For each ad, banner or any other content you want to track you will have to create a content block. You can use either the attribute `data-track-content` or the CSS class `matomoTrackContent`. The attribute does not require any value.

Examples:

Expand All @@ -103,7 +103,7 @@ Examples:
// content target = ""

// or
<img src="img-en.jpg" class="piwikTrackContent"/>
<img src="img-en.jpg" class="matomoTrackContent"/>
// content name = absolutePath(img-en.jpg)
// content piece = absoluteUrl(img-en.jpg)
// content target = ""
Expand All @@ -115,7 +115,7 @@ As you can see in these examples we do detect the content piece and name automat

* The simplest scenario is to provide an HTML attribute `data-content-piece="foo"` including a value anywhere within the content block or in the content block element itself.
* If there is no such attribute we will check whether the content piece element is media (audio, video, image, pdf, ...) and we will try to find the URL of the media automatically.
* To find the content piece element we will search for an element having the attribute `data-content-piece` or the CSS class `piwikContentPiece`. This attribute/class can be specified anywhere within a content block. If we do not find any specific content piece element we will use the content block element.
* To find the content piece element we will search for an element having the attribute `data-content-piece` or the CSS class `matomoContentPiece`. This attribute/class can be specified anywhere within a content block. If we do not find any specific content piece element we will use the content block element.
* In case of video or audio elements, when there are multiple sources defined, we will choose the URL of the first source.
* We will automatically build a fully qualified URL of the source in case we find one. This allows you to see a preview in the UI and to know exactly which media was displayed in case relative paths are used.
* If we haven't found anything we will fall back to use the value "Unknown". In such a case you should set the attribute `data-content-piece` telling us explicitly what the content is.
Expand All @@ -141,7 +141,7 @@ As you can see a specific value for the content piece is defined which can be us

// or
<a href="https://www.example.com" data-track-content>
<img src="img-en.jpg" class="piwikContentPiece"/>
<img src="img-en.jpg" class="matomoContentPiece"/>
</a>
// content name = absolutePath(img-en.jpg)
// content piece = absoluteUrl(img-en.jpg)
Expand All @@ -157,7 +157,7 @@ In these examples we were able to detect the name and the piece of the content a

// or
<a href="https://www.example.com" data-track-content>
<p class="piwikContentPiece">Lorem ipsum dolor sit amet</p>
<p class="matomoContentPiece">Lorem ipsum dolor sit amet</p>
</a>
// content name = Unknown
// content piece = Unknown
Expand Down Expand Up @@ -247,7 +247,7 @@ In case there is no content name and no content piece we will fall back to the `

#### How do we detect the content target element?

The content target element will be used to find a URL as this element is usually a link or a button. We detect the target element either by the attribute `data-content-target` or by the class `.piwikContentTarget`. If no such element can be found we will fall back to the content block element.
The content target element will be used to find a URL as this element is usually a link or a button. We detect the target element either by the attribute `data-content-target` or by the class `.matomoContentTarget`. If no such element can be found we will fall back to the content block element.

#### How do we detect the content target?

Expand Down Expand Up @@ -297,7 +297,7 @@ As the `data-content-target` attribute is set with a value, we can detect the co

```html
<div data-track-content>
<a href="https://www.example.com" class="piwikContentTarget">Click me</a>
<a href="https://www.example.com" class="matomoContentTarget">Click me</a>
</div>
// content name = Unknown
// content piece = Unknown
Expand Down Expand Up @@ -380,12 +380,12 @@ Anchor and all other kind of links will be tracked using an XHR.

#### How to prevent the automatic tracking of an interaction?

Maybe you do not want us to track any interaction automatically as explained before. To do so you can either set the attribute `data-content-ignoreinteraction` or the CSS class `piwikContentIgnoreInteraction` on the content target element. In single page application you might have to disable automatic tracking of an interaction as otherwise a page reload and a redirect would occur.
Maybe you do not want us to track any interaction automatically as explained before. To do so you can either set the attribute `data-content-ignoreinteraction` or the CSS class `matomoContentIgnoreInteraction` on the content target element. In single page application you might have to disable automatic tracking of an interaction as otherwise a page reload and a redirect would occur.

Examples

```html
<a href="https://outlink.example.com" class="piwikTrackContent piwikContentIgnoreInteraction">Add to shopping cart</a>
<a href="https://outlink.example.com" class="matomoTrackContent matomoContentIgnoreInteraction">Add to shopping cart</a>
//
<div data-track-content>
<a href="https://outlink.example.com" data-content-target data-content-ignoreinteraction>Add to shopping cart</a>
Expand Down
2 changes: 1 addition & 1 deletion docs/4.x/form-analytics/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,7 +138,7 @@ Example:
_paq.push(['FormAnalytics.disable']);

// or if you are using multiple Piwik trackers and only want to disable it for a specific tracker:
var tracker = Matomo.getTracker(piwikUrl, piwikSiteId);
var tracker = Matomo.getTracker(matomoUrl, matomoSiteId);
tracker.FormAnalytics.disable();
```

Expand Down
2 changes: 1 addition & 1 deletion docs/4.x/heatmap-session-recording/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -207,7 +207,7 @@ Example:
_paq.push(['HeatmapSessionRecording.disable']);

// or if you are using multiple Piwik trackers and only want to disable it for a specific tracker:
var tracker = Matomo.getAsyncTracker(piwikUrl, piwikSiteId);
var tracker = Matomo.getAsyncTracker(matomoUrl, matomoSiteId);
tracker.HeatmapSessionRecording.disable();
```

Expand Down
2 changes: 1 addition & 1 deletion docs/4.x/media-analytics/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ Example:
_paq.push(['MediaAnalytics.disableTrackEvents']);

// or if you are using multiple Piwik trackers and only want to disable it for a specific tracker:
var tracker = Matomo.getAsyncTracker(piwikUrl, piwikSiteId);
var tracker = Matomo.getAsyncTracker(matomoUrl, matomoSiteId);
tracker.MediaAnalytics.disableTrackEvents();
```

Expand Down
12 changes: 6 additions & 6 deletions docs/4.x/tracking-javascript-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -698,10 +698,10 @@ _paq.push(['trackPageView']);

### Recording a click as a download

If you want to force Piwik to consider a link as a download, you can add the 'piwik_download' css class to the link:
If you want to force Piwik to consider a link as a download, you can add the `matomo_download` or `piwik_download` css class to the link:

```html
<a href='last.php' class='piwik_download'>Link I want to track as a download</a>
<a href='last.php' class='matomo_download'>Link I want to track as a download</a>
```

Note: you can customize and rename the CSS class used to force a click to be recorded as a download:
Expand Down Expand Up @@ -757,10 +757,10 @@ This will result in clicks on a link `<a href='https://example.com' class='no-tr

#### Disabling for a specific link

If you want to ignore download or outlink tracking on a specific link, you can add the 'piwik_ignore' css class to it:
If you want to ignore download or outlink tracking on a specific link, you can add the `matomo_ignore` or 'piwik_ignore' css class to it:

```html
<a href='https://builds.matomo.org/latest.zip' class='piwik_ignore'>File I don't want to track as a download</a>
<a href='https://builds.matomo.org/latest.zip' class='matomo_ignore'>File I don't want to track as a download</a>
```

## Asking for consent
Expand Down Expand Up @@ -955,7 +955,7 @@ Alternatively to using the RollUp Reporting plugin you can duplicate the trackin
// We will also collect the website data into Website ID = 7
var websiteIdDuplicate = 7;
// The data will be duplicated into `piwik.example.org/matomo.php`
_paq.push(['addTracker', piwikUrl = u+'matomo.php', websiteIdDuplicate]);
_paq.push(['addTracker', u+'matomo.php', websiteIdDuplicate]);
// Your data is now tracked in both website ID 1 and website 7 into your piwik.example.org server!
```

Expand Down Expand Up @@ -992,7 +992,7 @@ The example below shows how to use `addTracker` method to track the same analyt

### Customise one of the tracker object instances

Note: by default any tracker added via `addTracker` is configured the same as the main default tracker object (regarding cookies, custom dimensions, user id, download & link tracking, domains and sub-domains, etc.). If you want to configure one of the Piwik tracker object instances that was added via `addTracker`, you may call the `Piwik.getAsyncTracker(optionalPiwikUrl, optionalPiwikSiteId)` method. This method returns the tracker instance object which you can configure differently than the main JavaScript tracker object instance.
Note: by default any tracker added via `addTracker` is configured the same as the main default tracker object (regarding cookies, custom dimensions, user id, download & link tracking, domains and sub-domains, etc.). If you want to configure one of the Piwik tracker object instances that was added via `addTracker`, you may call the `Matomo.getAsyncTracker(optionalMatomoUrl, optionalPiwikSiteId)` method. This method returns the tracker instance object which you can configure differently than the main JavaScript tracker object instance.

### Duplicate the tracking data when calling the JavaScript API directly (not via `_paq.push`)

Expand Down
6 changes: 3 additions & 3 deletions docs/4.x/tracking-javascript.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Read also the **[JavaScript Tracking Client](/guides/tracking-javascript-guide)*
### Requesting the Tracker Instance from the Piwik Class

* `Matomo.getTracker( trackerUrl, siteId )` - Get a new instance of the Tracker
* `Matomo.getAsyncTracker( optionalPiwikUrl, optionalPiwikSiteId )` - Get the internal instance of the Tracker used for asynchronous tracking
* `Matomo.getAsyncTracker( optionalMatomoUrl, optionalMatomoSiteId )` - Get the internal instance of the Tracker used for asynchronous tracking

### Using the Tracker Object

Expand Down Expand Up @@ -47,11 +47,11 @@ Read also the **[JavaScript Tracking Client](/guides/tracking-javascript-guide)*
* `getMatomoUrl()` - Return the Matomo server URL.
* `getPiwikUrl()` - Deprecated, use `getMatomoUrl()` instead.
* `getCurrentUrl()` - Return the current url of the page that is currently being visited. If a custom URL was set before calling this method, the custom URL will be returned.
* `setDownloadClasses( string | array )` - Set classes to be treated as downloads (in addition to piwik_download)
* `setDownloadClasses( string | array )` - Set classes to be treated as downloads (in addition to matomo_download)
* `setDownloadExtensions( string | array )` - Set list of file extensions to be recognized as downloads. Example: 'doc' or ['doc', 'xls']
* `addDownloadExtensions( string | array )` - Specify additional file extensions to be recognized as downloads. Example: 'doc' or ['doc', 'xls']
* `removeDownloadExtensions( string | array )` - Specify file extensions to be removed from the list of download file extensions. Example: 'doc' or ['doc', 'xls']
* `setIgnoreClasses( string | array )` - Set classes to be ignored if present in link (in addition to piwik_ignore)
* `setIgnoreClasses( string | array )` - Set classes to be ignored if present in link (in addition to matomo_ignore and piwik_ignore)
* `setLinkClasses( string | array )` - Set classes to be treated as outlinks (in addition to piwik_link)
* `setLinkTrackingTimer( integer )` - Set delay for link tracking in milliseconds.
* `getLinkTrackingTimer()` - Get delay for link tracking (in milliseconds).
Expand Down