diff --git a/docs/4.x/ab-tests.md b/docs/4.x/ab-tests.md index 1b1a8ca68..cd4382497 100644 --- a/docs/4.x/ab-tests.md +++ b/docs/4.x/ab-tests.md @@ -8,12 +8,12 @@ subGuides: --- # A/B Testing - Experiments -This section contains guides that will help you run experiments (A/B tests) on your websites and apps using Piwik. +This section contains guides that will help you run experiments (A/B tests) on your websites and apps using Matomo. -[A/B Testing](https://www.ab-tests.net/) is a plugin for Piwik that can be purchased on -the [Piwik Marketplace](https://plugins.piwik.org/AbTesting). It is developed by [InnoCraft](https://www.innocraft.com), -the makers of Piwik. If you want to learn more about this plugin we recommend to have a look at the developer guides, -the [A/B Testing User Guide](https://piwik.org/docs/ab-testing/) and the [A/B Testing FAQs](https://piwik.org/faq/ab-testing/). +[A/B Testing](https://www.ab-tests.net/) is a plugin for Matomo that can be purchased on +the [Matomo Marketplace](https://plugins.matomo.org/AbTesting). It is developed by [InnoCraft](https://www.innocraft.com), +the makers of Matomo. If you want to learn more about this plugin we recommend to have a look at the developer guides, +the [A/B Testing User Guide](https://matomo.org/docs/ab-testing/) and the [A/B Testing FAQs](https://matomo.org/faq/ab-testing/). An A/B test lets you compare different versions and see which variation makes you more successful. A/B tests are also known as experiments or split tests. In an A/B test you show two or more different variations to your @@ -24,6 +24,6 @@ way lets you take data-driven decisions that maximise your success. This section contains the following developer guides that will help you running experiments: * **Websites (JavaScript)**: Run experiments on your website in the browser. Follow the [website implementation guide](/guides/ab-tests/browser) when you use the Piwik JavaScript Tracker on your website. -* **Websites (Server-side)**: Run experiments server-side by using any A/B testing framework of your choice by following the [server side implementation guide](/guides/ab-tests/server) as long as you are also using the Piwik JavaScript tracker (works with [PHP](https://github.com/matomo-org/piwik-php-tracker), [Java](https://github.com/matomo-org/piwik-java-tracker), [C#](https://github.com/matomo-org/piwik-dotnet-tracker), [Python](https://github.com/matomo-org/piwik-python-tracker/tree/dev), ...). -* **Mobile, Desktop Apps & Games**: Run experiments using any A/B testing framework of your choice by following the [apps implementation guide](/guides/ab-tests/apps) when you are using a Piwik Tracker SDK (eg [Android SDK](https://github.com/matomo-org/piwik-sdk-android), [iOS SDK](https://github.com/matomo-org/piwik-sdk-ios), [C#](https://github.com/matomo-org/piwik-dotnet-tracker), [PHP](https://github.com/matomo-org/piwik-php-tracker), [Java](https://github.com/matomo-org/piwik-java-tracker), [Python](https://github.com/matomo-org/piwik-python-tracker/tree/dev)) to track your application. +* **Websites (Server-side)**: Run experiments server-side by using any A/B testing framework of your choice by following the [server side implementation guide](/guides/ab-tests/server) as long as you are also using the Piwik JavaScript tracker (works with [PHP](https://github.com/matomo-org/matomo-php-tracker), [Java](https://github.com/matomo-org/piwik-java-tracker), [C#](https://github.com/matomo-org/piwik-dotnet-tracker), [Python](https://github.com/matomo-org/piwik-python-tracker/tree/dev), ...). +* **Mobile, Desktop Apps & Games**: Run experiments using any A/B testing framework of your choice by following the [apps implementation guide](/guides/ab-tests/apps) when you are using a Piwik Tracker SDK (eg [Android SDK](https://github.com/matomo-org/matomo-sdk-android), [iOS SDK](https://github.com/matomo-org/matomo-sdk-ios), [C#](https://github.com/matomo-org/piwik-dotnet-tracker), [PHP](https://github.com/matomo-org/piwik-php-tracker), [Java](https://github.com/matomo-org/piwik-java-tracker), [Python](https://github.com/matomo-org/piwik-python-tracker/tree/dev)) to track your application. * **Campaigns & Email Marketing**: Track how different campaigns affect the browsing behaviour on your website by following the [campaign implementation guide](/guides/ab-tests/campaign). diff --git a/docs/4.x/ab-tests/apps.md b/docs/4.x/ab-tests/apps.md index ea8fa4e22..01b6a2d83 100644 --- a/docs/4.x/ab-tests/apps.md +++ b/docs/4.x/ab-tests/apps.md @@ -5,17 +5,17 @@ title: Mobile & Desktop Apps # Running an A/B test experiment in an app eg. Android, iOS, desktop app or games You can run experiments in apps by using any A/B testing framework of your choice if you are tracking your users -via one of the Piwik SDKs (eg [Android SDK](https://github.com/matomo-org/piwik-sdk-android), -[iOS SDK](https://github.com/matomo-org/piwik-sdk-ios), [C#](https://github.com/matomo-org/piwik-dotnet-tracker), -[PHP](https://github.com/matomo-org/piwik-php-tracker), [Java](https://github.com/matomo-org/piwik-java-tracker), -[Python](https://github.com/matomo-org/piwik-python-tracker/tree/dev)). +via one of the Piwik SDKs (eg [Android SDK](https://github.com/matomo-org/matomo-sdk-android), +[iOS SDK](https://github.com/matomo-org/matomo-sdk-ios), [C#](https://github.com/matomo-org/piwik-dotnet-tracker), +[PHP](https://github.com/matomo-org/matomo-php-tracker), [Java](https://github.com/matomo-org/piwik-java-tracker), +[Python](https://github.com/matomo-org/matomo-python-tracker/tree/dev)). This guide requires that you track your application via a [Piwik Tracking SDK](/guides/tracking-api-clients), -via the [Tracking HTTP API](/api-reference/tracking-api) or any other [Piwik Tracking Integration](https://piwik.org/integrate). +via the [Tracking HTTP API](/api-reference/tracking-api) or any other [Piwik Tracking Integration](https://matomo.org/integrate). ## Creating an experiment -First you need to create an A/B test experiment in Piwik: read the [A/B testing user guide](https://piwik.org/docs/ab-testing/) to learn more. +First you need to create an A/B test experiment in Piwik: read the [A/B testing user guide](https://matomo.org/docs/ab-testing/) to learn more. When you are asked on which target pages the experiment should be activated, we recommend selecting "Visitors enter this experiment on any page". @@ -50,7 +50,7 @@ $experiment->trackVariationActivation($piwikPhpTracker); ### Sending the name of the activated variation to Piwik So far you have created and implemented the experiment, so users get to see different versions of your app. -Now you need to let Piwik know which variation was activated for your current user by tracking a [Piwik event](https://piwik.org/docs/event-tracking/): +Now you need to let Piwik know which variation was activated for your current user by tracking a [Piwik event](https://matomo.org/docs/event-tracking/): ```php // example tracking request via PHP Piwik Tracker diff --git a/docs/4.x/ab-tests/browser.md b/docs/4.x/ab-tests/browser.md index 3e5e05d1c..6d40dedb8 100644 --- a/docs/4.x/ab-tests/browser.md +++ b/docs/4.x/ab-tests/browser.md @@ -12,28 +12,28 @@ and what to do when an experiment is finished. ## Creating an experiment -Read the [A/B testing user guide](https://piwik.org/docs/ab-testing/) to learn more about creating an A/B test experiment. +Read the [A/B testing user guide](https://matomo.org/docs/ab-testing/) to learn more about creating an A/B test experiment. ## Embedding the A/B Testing JavaScript framework -The [A/B Testing plugin](https://www.ab-tests.net) directly adds the JavaScript A/B testing framework to your Piwik JavaScript tracker file `/piwik.js` +The [A/B Testing plugin](https://www.ab-tests.net) directly adds the JavaScript A/B testing framework to your Matomo JavaScript tracker file `/matomo.js` and is therefore loaded automatically with the [Piwik JavaScript Tracking Code](/guides/tracking-javascript-guide). -This will work by default as long as the file `piwik.js` in your Piwik directory is writable by the webserver/PHP. +This will work by default as long as the file `matomo.js` in your Piwik directory is writable by the webserver/PHP. To check whether this works by default for you, login into Piwik as a Super User, go to Administration, and open the "System Check" report. -If the System Check displays a warning for "Writable Piwik.js" then [learn below in the FAQ how to solve this](#how-do-i-include-the-ab-testing-framework-when-my-piwikjs-file-is-not-writable). +If the System Check displays a warning for "Writable Matomo.js" then [learn below in the FAQ how to solve this](#how-do-i-include-the-ab-testing-framework-when-my-matomojs-file-is-not-writable). -### Loading piwik.js synchronously as early as possible +### Loading matomo.js synchronously as early as possible To prevent any flickering / flashing of content when you run your experiments, you need to make sure to load the -`piwik.js` tracker file as early as possible. Edit your JavaScript tracking code as follows: +`matomo.js` tracker file as early as possible. Edit your JavaScript tracking code as follows: -* Move the Piwik Tracking Code that loads the `piwik.js` file into the HTML `
` +* Move the Piwik Tracking Code that loads the `matomo.js` file into the HTML `` * Load the file synchronously instead of asynchronously by: - 1. Removing the two lines containing: `var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0]; g.type='text/javascript'; g.async=true; g.defer=true; g.src=u+'piwik.js'; s.parentNode.insertBefore(g,s);` - 2. Adding the following line after the closing `` element: `` + 1. Removing the two lines containing: `var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0]; g.type='text/javascript'; g.async=true; g.defer=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);` + 2. Adding the following line after the closing `` element: `` 3. Your JavaScript tracker code should look like this: ```html @@ -43,11 +43,11 @@ To prevent any flickering / flashing of content when you run your experiments, y // [...] (function() { var u = "//$yourPiwikDomain/"; - _paq.push(['setTrackerUrl', u+'piwik.php']); + _paq.push(['setTrackerUrl', u+'matomo.php']); _paq.push(['setSiteId', 'X']); })(); - @@ -449,9 +449,9 @@ server and afterwards force the same variation in the client. ### How do I know when the A/B Testing framework has been loaded and initialized? The A/B Testing framework executes a method `window.piwikAbTestingAsyncInit` as soon as it has been loaded. When you -specify such a method, you can be sure that variables like `Piwik.AbTesting` are available. If you load the `piwik.js` -file synchronously as recommended, you can be sure that `Piwik.AbTesting` will be defined just after the include of -`piwik.js` +specify such a method, you can be sure that variables like `Matomo.AbTesting` are available. If you load the `matomo.js` +file synchronously as recommended, you can be sure that `Matomo.AbTesting` will be defined just after the include of +`matomo.js` ### Can I integrate the A/B Tests when I use a framework like Angular, Ember, ReactJS? @@ -459,7 +459,7 @@ Yes, you can run your A/B tests in any popular JavaScript framework. We recommend [creating your experiment without _paq.push](#how-do-i-implement-an-experiment-without-using-_paqpush) as follows: ```js -var Experiment = Piwik.AbTesting.Experiment; +var Experiment = Matomo.AbTesting.Experiment; var myExperiment = new Experiment({ // [...] @@ -492,7 +492,7 @@ experiment as follows: ```html @@ -37,9 +37,9 @@ The tracking code looks as follows: In your tracking code, `{$MATOMO_URL}` would be replaced by your Piwik URL and `{$IDSITE}` would be replaced by the idsite of the website you are tracking in Piwik. -This code might look a bit strange to those of you familiar with JavaScript, but that is because it is made to run asynchronously. In other words, browsers will not wait for the `piwik.js` file to be downloaded in order to show your page. +This code might look a bit strange to those of you familiar with JavaScript, but that is because it is made to run asynchronously. In other words, browsers will not wait for the `matomo.js` file to be downloaded in order to show your page. -For asynchronous tracking, configuration and tracking calls are pushed onto the global `_paq` array for execution, independent of the asynchronous loading of `piwik.js`. The format is: +For asynchronous tracking, configuration and tracking calls are pushed onto the global `_paq` array for execution, independent of the asynchronous loading of `matomo.js`. The format is: ```javascript _paq.push([ 'API_method_name', parameter_list ]); @@ -59,7 +59,7 @@ _paq.push(['setCustomVariable','1','VisitorType','Member']); _paq.push([ function() { var customVariable = this.getCustomVariable(1); }]); ``` -You can push to the `_paq` array even after the `piwik.js` file has been loaded and run. +You can push to the `_paq` array even after the `matomo.js` file has been loaded and run. If your Piwik tracking code doesn't look like this one, you may be using the deprecated version. Older versions still work as expected and will track your visitors, but we highly recommend that you update your pages to use the most recent tracking code. @@ -105,7 +105,7 @@ To track any user interaction or click with Piwik, you can manually call the Jav Freedom page ``` -You can learn more about [Tracking Events](https://piwik.org/docs/event-tracking/#tracking-events) in the user guide. +You can learn more about [Tracking Events](https://matomo.org/docs/event-tracking/#tracking-events) in the user guide. ### Manually trigger goal conversions @@ -132,7 +132,7 @@ You can also register a conversion for this goal with a custom revenue. For exam _paq.push(['trackGoal', 1, getCartValue(); ?>]); ``` -Find more information about goal tracking in Piwik in the [**Tracking Goals**](https://piwik.org/docs/tracking-goals-web-analytics/) documentation. +Find more information about goal tracking in Piwik in the [**Tracking Goals**](https://matomo.org/docs/tracking-goals-web-analytics/) documentation. ### Accurately measure the time spent on each page @@ -163,13 +163,13 @@ Note: When testing the heart beat timer, remember to make sure the browser tab h ## Ecommerce tracking -Piwik allows for advanced and powerful Ecommerce tracking. Check out the [Ecommerce Analytics](https://piwik.org/docs/ecommerce-analytics/) documentation for more information about Ecommerce reports and how to set up Ecommerce tracking. +Piwik allows for advanced and powerful Ecommerce tracking. Check out the [Ecommerce Analytics](https://matomo.org/docs/ecommerce-analytics/) documentation for more information about Ecommerce reports and how to set up Ecommerce tracking. ## Internal search tracking -Piwik offers advanced [Site Search Analytics](https://piwik.org/docs/site-search/) feature, letting you track how your visitors use your internal website search engine. By default, Piwik can read URL parameters that will contain the search keyword. However, you can also record the site search keyword manually using the JavaScript function `trackSiteSearch(...)` +Piwik offers advanced [Site Search Analytics](https://matomo.org/docs/site-search/) feature, letting you track how your visitors use your internal website search engine. By default, Piwik can read URL parameters that will contain the search keyword. However, you can also record the site search keyword manually using the JavaScript function `trackSiteSearch(...)` -In your website, in standard pages, you would typically have a call to record Page views via `piwikTracker.trackPageView()`. On your search result page, you would call **instead** `piwikTracker.trackSiteSearch(keyword, category, searchCount)` function to record the internal search request. Note: the 'keyword' parameter is required, but category and searchCount are optional. +In your website, in standard pages, you would typically have a call to record Page views via `matomoTracker.trackPageView()`. On your search result page, you would call **instead** `piwikTracker.trackSiteSearch(keyword, category, searchCount)` function to record the internal search request. Note: the 'keyword' parameter is required, but category and searchCount are optional. ```javascript _paq.push(['trackSiteSearch', @@ -185,11 +185,11 @@ _paq.push(['trackSiteSearch', // _paq.push(['trackPageView']); ``` -We also highly recommend to set the searchCount parameter, as Piwik will specifically report "No Result Keywords", ie. Keywords that were searched, but did not return any result. It is usually very interesting to know what users search for but can't find (yet?) on your website. Learn more about [Site Search Analytics in the User Doc](https://piwik.org/docs/site-search/). +We also highly recommend to set the searchCount parameter, as Piwik will specifically report "No Result Keywords", ie. Keywords that were searched, but did not return any result. It is usually very interesting to know what users search for but can't find (yet?) on your website. Learn more about [Site Search Analytics in the User Doc](https://matomo.org/docs/site-search/). ## Custom variables -Custom variables are a powerful feature that enable you to track custom values for each visit, and/or each page view. Please see the [Tracking custom variables](https://piwik.org/docs/custom-variables/) documentation page for general information. +Custom variables are a powerful feature that enable you to track custom values for each visit, and/or each page view. Please see the [Tracking custom variables](https://matomo.org/docs/custom-variables/) documentation page for general information. You can set up up to 5 custom variables (name and value) for each visit to your website, and/or up to 5 custom variables for each page view. If you set a custom variable to a visitor, when he comes back one hour or two days later, it will be a new visit and his/her custom variables will be empty. @@ -198,7 +198,7 @@ There are two "scopes" which you can set your custom variables to. The "scope" i - when scope = "visit", the custom variable's name and value will be stored in the visit in the database. You can therefore store up to 5 custom variables of scope "visit" for each visit. - when scope = "page", the custom variable's name and value will be stored for the page view being tracked. You can therefore store up to 5 custom variables of scope "page" for each page view. -The "index" parameter is the custom variable slot index, an integer from 1 to 5. (note: [read this FAQ](https://piwik.org/faq/how-to/faq_17931/) if you need more than the default 5 slots). +The "index" parameter is the custom variable slot index, an integer from 1 to 5. (note: [read this FAQ](https://matomo.org/faq/how-to/faq_17931/) if you need more than the default 5 slots). Custom variable statistics are reported in Piwik under **Visitors > custom variables**. Both custom variables of scope "visit" and "page" are aggregated in this report. @@ -307,7 +307,7 @@ _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. +[Custom Dimensions](https://matomo.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.matomo.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://matomo.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 @@ -362,7 +362,7 @@ This function can be used to get the value of a Custom Dimension. It will only w ## User ID -[User ID](https://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: +[User ID](https://matomo.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: - You must assign a unique and persistent non-empty string that represents each logged-in user. Typically, this ID will be an email address or a username provided by your authentication system. - You must set the user ID for each pageview, otherwise the pageview will be tracked without the user ID set. @@ -419,7 +419,7 @@ _paq.push(['appendToTrackingUrl', '']); ## Content Tracking -There are several ways to track content impressions and interactions manually, semi-automatically and automatically. Please be aware that content impressions will be tracked using bulk tracking which will always send a `POST` request, even if `GET` is configured which is the default. For more details have a look at the [in-depth guide to Content Tracking](https://developer.piwik.org/guides/content-tracking). +There are several ways to track content impressions and interactions manually, semi-automatically and automatically. Please be aware that content impressions will be tracked using bulk tracking which will always send a `POST` request, even if `GET` is configured which is the default. For more details have a look at the [in-depth guide to Content Tracking](https://developer.matomo.org/guides/content-tracking). ### Track all content impressions within a page @@ -487,10 +487,10 @@ You should use the methods `trackContentImpression(contentName, contentPiece, co Example ```javascript -_paq.push(['trackContentImpression', 'Content Name', 'Content Piece', 'http://www.example.com']); +_paq.push(['trackContentImpression', 'Content Name', 'Content Piece', 'https://www.example.com']); div.addEventListener('click', function () { - _paq.push(['trackContentInteraction', 'tabActivated', 'Content Name', 'Content Piece', 'http://www.example.com']); + _paq.push(['trackContentInteraction', 'tabActivated', 'Content Name', 'Content Piece', 'https://www.example.com']); }); ``` @@ -533,7 +533,7 @@ _paq.push(['trackPageView']); To accurately track a visitor across different domain names into a single visit within one Piwik website, we need to set up what is called Cross Domain linking. Cross domain tracking in Piwik makes sure that when the visitor visits multiple websites and domain names, the visitor data will be stored in the same visit and that the visitor ID is reused across domain names. A typical use case where cross domain is needed is, for example, when an ecommerce online store is on `www.awesome-shop.com` and the ecommerce shopping cart technology is on another domain such as `secure.cart.com`. -Cross domain linking uses a combination of the two tracker methods `setDomains` and `enableCrossDomainLinking`. Learn how to set up cross-domain linking in our guide: [How do I accurately measure a same visitor across multiple domain names (cross domain linking)?](https://piwik.org/faq/how-to/faq_23654/) +Cross domain linking uses a combination of the two tracker methods `setDomains` and `enableCrossDomainLinking`. Learn how to set up cross-domain linking in our guide: [How do I accurately measure a same visitor across multiple domain names (cross domain linking)?](https://matomo.org/faq/how-to/faq_23654/) ### Tracking subdirectories of a domain in separate websites @@ -597,7 +597,7 @@ Notes: * since the wildcard can match several paths, calls to `setCookieDomain` or `setCookiePath` are omitted to ensure tracking cookie is correctly shared for all pages matching the wildcard. -For more information about tracking websites and subdomains in Piwik, see the FAQ: [How to configure Piwik to monitor several websites, domains and sub-domains](https://piwik.org/faq/new-to-piwik/#faq_104) +For more information about tracking websites and subdomains in Piwik, see the FAQ: [How to configure Piwik to monitor several websites, domains and sub-domains](https://matomo.org/faq/new-to-piwik/#faq_104) ## Download and Outlink tracking @@ -644,7 +644,7 @@ Learn more about this use case [Tracking subdirectories of a domain in separate If you want to force Piwik to consider a link as an outlink (links to the current domain or to one of the alias domains), you can add the 'piwik_link' css class to the link: ```html -Link I want to track as an outlink +Link I want to track as an outlink ``` Note: you can customize and rename the CSS class used to force a click to be recorded as an outlink: @@ -661,7 +661,7 @@ _paq.push(['trackPageView']); Alternatively, you can use JavaScript to manually trigger a click on an outlink (it will work the same for page views or file downloads). In this example, custom outlink is trigged when the email address is clicked: ```html -namexyz@mydomain.co.uk +namexyz@mydomain.co.uk ``` ### Tracking file downloads @@ -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 -Link I want to track as a download +Link I want to track as a download ``` Note: you can customize and rename the CSS class used to force a click to be recorded as a download: @@ -718,7 +718,7 @@ _paq.push(['trackPageView']); Alternatively, you can use JavaScript to manually trigger a click on a download. In this example, custom download is trigged when the link is clicked: ```html -Download +Download ``` ### Changing the Pause Timer @@ -753,14 +753,14 @@ _paq.push(['setIgnoreClasses', "no-tracking"]); _paq.push(['trackPageView']); ``` -This will result in clicks on a link `Test` not being counted. +This will result in clicks on a link `Test` not being counted. #### 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 -File I don't want to track as a download +File I don't want to track as a download ``` ## Asking for consent @@ -931,7 +931,7 @@ document.addEventListener("DOMContentLoaded", function(event) { ## Multiple Piwik trackers -By default, the Piwik JavaScript Tracking code collects your analytics data into one Piwik server. The Piwik service URL is specified in your JavaScript Tracking code (for example: `var u="//piwik.example.org";`). In some cases, you may want to track your analytics data into more than just one Piwik server or into multiple websites on the same Piwik server. +By default, the Piwik JavaScript Tracking code collects your analytics data into one Piwik server. The Piwik service URL is specified in your JavaScript Tracking code (for example: `var u="//matomo.example.org";`). In some cases, you may want to track your analytics data into more than just one Piwik server or into multiple websites on the same Piwik server. *If you haven't upgraded yet to Piwik 2.16.2 or later, please upgrade now! (Instructions for 2.16.1 or older versions are found below.)* @@ -941,21 +941,21 @@ You may need to collect a duplicate of your web analytics data into the same Piw #### Recommended solution: use RollUp Reporting plugin -When you need to duplicate data into another website, or consolidate several websites into one or more groups (called RollUps) the recommended solution is to use the [RollUp Reporting premium plugin](https://plugins.piwik.org/RollUpReporting). Using this plugin has several advantages over the other solution as you can easily group one or more websites together, and the RollUps do not cause the tracking data to be duplicated which improves overall performance. +When you need to duplicate data into another website, or consolidate several websites into one or more groups (called RollUps) the recommended solution is to use the [RollUp Reporting premium plugin](https://plugins.matomo.org/RollUpReporting). Using this plugin has several advantages over the other solution as you can easily group one or more websites together, and the RollUps do not cause the tracking data to be duplicated which improves overall performance. #### Alternative solution: duplicate the tracking data Alternatively to using the RollUp Reporting plugin you can duplicate the tracking data. To duplicate the data you can call `addTracker` with a Piwik URL and your website ID where to duplicate the data: ```js - var u="//piwik.example.org/"; + var u="//matomo.example.org/"; _paq.push(['setTrackerUrl', u+'matomo.php']); _paq.push(['setSiteId', '1']); // 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! ``` @@ -972,7 +972,7 @@ The example below shows how to use `addTracker` method to track the same analyt _paq.push(['enableLinkTracking']); (function() { - var u="//piwik.example.org/"; + var u="//matomo.example.org/"; _paq.push(['setTrackerUrl', u+'matomo.php']); _paq.push(['setSiteId', '1']); @@ -985,14 +985,14 @@ The example below shows how to use `addTracker` method to track the same analyt // That's it! var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0]; - g.type='text/javascript'; g.async=true; g.defer=true; g.src=u+'piwik.js'; s.parentNode.insertBefore(g,s); + g.type='text/javascript'; g.async=true; g.defer=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s); })(); ``` ### 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`) @@ -1000,27 +1000,27 @@ It is possible to track your analytics data into either a different website ID o ```html ``` -The `piwikAsyncInit()` method will be executed once the Piwik tracker is loaded and initialized. In earlier versions you must load Piwik synchronous. +The `matomoAsyncInit()` method will be executed once the Piwik tracker is loaded and initialized. In earlier versions you must load Piwik synchronous. Note that you can also set the website ID and the Piwik tracker URL manually, instead of setting them in the getTracker call: ```javascript -// we replace Piwik.getTracker("http://example.com/piwik/", 12) -var piwikTracker = Piwik.getTracker(); -piwikTracker.setSiteId( 12 ); -piwikTracker.setTrackerUrl( "http://example.com/piwik/" ); -piwikTracker.trackPageView(); +// we replace Matomo.getTracker("https://example.com/matomo/", 12) +var matomoTracker = Matomo.getTracker(); +matomoTracker.setSiteId( 12 ); +matomoTracker.setTrackerUrl( "https://example.com/matomo/" ); +matomoTracker.trackPageView(); ``` ## JavaScript Tracker Reference @@ -1029,13 +1029,13 @@ View all features of the Tracking client in the [JavaScript Tracker Reference](/ ## Frequently Asked Questions -If you have any question about JavaScript Tracking in Piwik, [please search the website](https://piwik.org/), or [ask in the forums](https://forum.piwik.org). +If you have any question about JavaScript Tracking in Piwik, [please search the website](https://matomo.org/), or [ask in the forums](https://forum.matomo.org). -- [How do enable tracking for users without JavaScript?](https://piwik.org/faq/how-to/#faq_176) -- [How does Piwik track downloads?](https://piwik.org/faq/new-to-piwik/#faq_47) -- [How to track single-page websites and web applications](https://piwik.org/blog/2017/02/how-to-track-single-page-websites-using-piwik-analytics/) -- [How to track error pages and get the list of 404 and referrers urls.](https://piwik.org/faq/how-to/#faq_60) -- [How can I set custom groups of pages (structure) so that page view are aggregated by categories?](https://piwik.org/faq/how-to/#faq_62) -- [How do I set up Piwik to track multiple websites without revealing the Piwik server URL footprint in JS?](https://piwik.org/faq/how-to/#faq_132) -- [How do I customise the piwik.js being loaded on all my websites?](https://piwik.org/faq/how-to/faq_19087/) -- [How do I disable all tracking cookies used by Piwik in the javascript code?](https://piwik.org/faq/general/#faq_157) +- [How do enable tracking for users without JavaScript?](https://matomo.org/faq/how-to/#faq_176) +- [How does Piwik track downloads?](https://matomo.org/faq/new-to-piwik/#faq_47) +- [How to track single-page websites and web applications](https://matomo.org/blog/2017/02/how-to-track-single-page-websites-using-piwik-analytics/) +- [How to track error pages and get the list of 404 and referrers urls.](https://matomo.org/faq/how-to/#faq_60) +- [How can I set custom groups of pages (structure) so that page view are aggregated by categories?](https://matomo.org/faq/how-to/#faq_62) +- [How do I set up Piwik to track multiple websites without revealing the Piwik server URL footprint in JS?](https://matomo.org/faq/how-to/#faq_132) +- [How do I customise the matomo.js being loaded on all my websites?](https://matomo.org/faq/how-to/faq_19087/) +- [How do I disable all tracking cookies used by Piwik in the javascript code?](https://matomo.org/faq/general/#faq_157) diff --git a/docs/4.x/tracking-javascript.md b/docs/4.x/tracking-javascript.md index fd2156759..5dec7dd6e 100644 --- a/docs/4.x/tracking-javascript.md +++ b/docs/4.x/tracking-javascript.md @@ -11,8 +11,8 @@ Read also the **[JavaScript Tracking Client](/guides/tracking-javascript-guide)* ### Requesting the Tracker Instance from the Piwik Class -* `Piwik.getTracker( trackerUrl, siteId )` - Get a new instance of the Tracker -* `Piwik.getAsyncTracker( optionalPiwikUrl, optionalPiwikSiteId )` - Get the internal instance of the Tracker used for asynchronous tracking +* `Matomo.getTracker( trackerUrl, siteId )` - Get a new instance of the Tracker +* `Matomo.getAsyncTracker( optionalMatomoUrl, optionalMatomoSiteId )` - Get the internal instance of the Tracker used for asynchronous tracking ### Using the Tracker Object @@ -31,9 +31,9 @@ Read also the **[JavaScript Tracking Client](/guides/tracking-javascript-guide)* * `ping()` - Send a ping request. Ping requests do not track new actions. If they are sent within the standard visit length, they will extend the existing visit and the current last action for the visit. If sent after the standard visit length, ping requests will create a new visit using the last action in the last known visit. See also `enableHeartBeatTimer`. * `enableHeartBeatTimer( delayInSeconds )` - Install a Heart beat timer that will regularly send requests to Piwik in order to better measure the time spent on the page. These requests will be sent only when the user is actively viewing the page (when the tab is active and in focus). These requests will not track additional actions or pageviews. By default, `delayInSeconds` is set to 15 seconds. See also `ping` and the [developer guide](https://developer.matomo.org/guides/tracking-javascript-guide#accurately-measure-the-time-spent-on-each-page). * `enableLinkTracking( enable )` - Install link tracking on all applicable link elements. Set the enable parameter to true to use pseudo click-handler (treat middle click and open contextmenu as left click). A right click (or any click that opens the context menu) on a link will be tracked as clicked even if "Open in new tab" is not selected. If "false" (default), nothing will be tracked on open context menu or middle click. -* `enableCrossDomainLinking()` - Enable cross domain linking. By default, the visitor ID that identifies a unique visitor is stored in the browser's first party cookies. This means the cookie can only be accessed by pages on the same domain. If you own multiple domains and would like to track all the actions and pageviews of a specific visitor into the same visit, you may enable [cross domain linking (learn more)](https://piwik.org/faq/how-to/faq_23654/) . Whenever a user clicks on a link it will append a URL parameter `pk_vid` to the clicked URL which forwards the current visitor ID value to the page of the different domain. +* `enableCrossDomainLinking()` - Enable cross domain linking. By default, the visitor ID that identifies a unique visitor is stored in the browser's first party cookies. This means the cookie can only be accessed by pages on the same domain. If you own multiple domains and would like to track all the actions and pageviews of a specific visitor into the same visit, you may enable [cross domain linking (learn more)](https://matomo.org/faq/how-to/faq_23654/) . Whenever a user clicks on a link it will append a URL parameter `pk_vid` to the clicked URL which forwards the current visitor ID value to the page of the different domain. * `setCrossDomainLinkingTimeout( timeout )` - Set the cross domain linking timeout (in seconds). By default, the two visits across domains will be linked together when the link is clicked and the page is loaded within a 180 seconds timeout window.` -* `getCrossDomainLinkingUrlParameter()` - Get the query parameter to append to links to handle cross domain linking. Use this to add cross domain support for links that are added to the DOM dynamically. [Learn more about cross domain linking](https://piwik.org/faq/how-to/faq_23654/). +* `getCrossDomainLinkingUrlParameter()` - Get the query parameter to append to links to handle cross domain linking. Use this to add cross domain support for links that are added to the DOM dynamically. [Learn more about cross domain linking](https://matomo.org/faq/how-to/faq_23654/). ### Configuration of the Tracker Object @@ -42,21 +42,22 @@ Read also the **[JavaScript Tracking Client](/guides/tracking-javascript-guide)* * `setCustomUrl( string )` - Override the page's reported URL * `setReferrerUrl( string )` - Override the detected Http-Referer * `setSiteId( integer )` - Specify the website ID. Redundant: can be specified in `getTracker()` constructor. -* `setApiUrl( string )` - Specify the Piwik HTTP API URL endpoint. Points to the root directory of piwik, e.g. http://piwik.example.org/ or https://example.org/piwik/. This function is only useful when the 'Overlay' report is not working. By default, you do not need to use this function. +* `setApiUrl( string )` - Specify the Piwik HTTP API URL endpoint. Points to the root directory of piwik, e.g. https://matomo.example.org/ or https://example.org/matomo/. This function is only useful when the 'Overlay' report is not working. By default, you do not need to use this function. * `setTrackerUrl( string )` - Specify the Piwik server URL. Redundant: can be specified in `getTracker()` constructor. -* `getPiwikUrl()` - Return the Piwik server URL. -* `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) +* `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 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). +* `getLinkTrackingTimer()` - Get delay for link tracking (in milliseconds). * `discardHashTag( bool )` - Set to true to not record the hash tag (anchor) portion of URLs * `setGenerationTimeMs(generationTime)` - By default Piwik uses the browser DOM Timing API to accurately determine the time it takes to generate and download the page. You may overwrite the value by specifying a milliseconds value here. -* `appendToTrackingUrl(appendToUrl)` - Append a custom string to the end of the HTTP request to piwik.php? +* `appendToTrackingUrl(appendToUrl)` - Append a custom string to the end of the HTTP request to matomo.php? * `setDoNotTrack( bool )` - Set to true to not track users who opt out of tracking using Mozilla's (proposed) Do Not Track setting. * `killFrame()` - Enable a frame-buster to prevent the tracked web page from being framed/iframed. * `redirectFile( url )` - Force the browser load the live URL if the tracked web page is loaded from a local file (e.g., saved to someone's desktop). @@ -64,32 +65,32 @@ Read also the **[JavaScript Tracking Client](/guides/tracking-javascript-guide)* * `getVisitorId()` - Return the 16 characters ID for the visitor * `getVisitorInfo()` - Return the visitor cookie contents in an array * `getAttributionInfo()` - Return the visitor attribution array (Referer information and / or Campaign name & keyword). - Attribution information is used by Piwik to credit the correct referrer ([first or last referrer](https://piwik.org/faq/general/#faq_106)) used when a user triggers a goal conversion. + Attribution information is used by Piwik to credit the correct referrer ([first or last referrer](https://matomo.org/faq/general/#faq_106)) used when a user triggers a goal conversion. You can also use any of the following functions to get specific attributes of data: - * `piwikTracker.getAttributionCampaignName()` - * `piwikTracker.getAttributionCampaignKeyword()` - * `piwikTracker.getAttributionReferrerTimestamp()` - * `piwikTracker.getAttributionReferrerUrl()` + * `matomoTracker.getAttributionCampaignName()` + * `matomoTracker.getAttributionCampaignKeyword()` + * `matomoTracker.getAttributionReferrerTimestamp()` + * `matomoTracker.getAttributionReferrerUrl()` * `getUserId()` - Return the User ID string if it was set. -* `setUserId( userId )` - Sets a [User ID](https://piwik.org/docs/user-id/) to this user (such as an email address or a username). +* `setUserId( userId )` - Sets a [User ID](https://matomo.org/docs/user-id/) to this user (such as an email address or a username). * `resetUserId` - Clears (un-set) the User ID. * `setCustomVariable (index, name, value, scope)` - Set 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 [Custom Dimensions plugin](https://plugins.piwik.org/CustomDimensions)) -* `deleteCustomDimension (customDimensionId)` - Delete a custom dimension. (requires [Custom Dimensions plugin](https://plugins.piwik.org/CustomDimensions)) -* `getCustomDimension (customDimensionId)` - Retrieve a custom dimension. (requires [Custom Dimensions plugin](https://plugins.piwik.org/CustomDimensions)) -* `setCampaignNameKey(name)` - Set campaign name parameter(s). (Help: [Customize Campaign name parameter names](https://piwik.org/faq/how-to/#faq_120)) -* `setCampaignKeywordKey(keyword)` - Set campaign keyword parameter(s). (Help: [Customize Campaign keyword parameter names](https://piwik.org/faq/how-to/#faq_120)) +* `setCustomDimension (customDimensionId, customDimensionValue)` - Set a custom dimension. (requires [Custom Dimensions plugin](https://plugins.matomo.org/CustomDimensions)) +* `deleteCustomDimension (customDimensionId)` - Delete a custom dimension. (requires [Custom Dimensions plugin](https://plugins.matomo.org/CustomDimensions)) +* `getCustomDimension (customDimensionId)` - Retrieve a custom dimension. (requires [Custom Dimensions plugin](https://plugins.matomo.org/CustomDimensions)) +* `setCampaignNameKey(name)` - Set campaign name parameter(s). (Help: [Customize Campaign name parameter names](https://matomo.org/faq/how-to/#faq_120)) +* `setCampaignKeywordKey(keyword)` - Set campaign keyword parameter(s). (Help: [Customize Campaign keyword parameter names](https://matomo.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. ### Ecommerce -Piwik provides [ecommerce analytics](https://piwik.org/docs/ecommerce-analytics/) that let you measure items added to carts, and learn detailed metrics about abandoned carts and purchased orders. +Piwik provides [ecommerce analytics](https://matomo.org/docs/ecommerce-analytics/) that let you measure items added to carts, and learn detailed metrics about abandoned carts and purchased orders. * `setEcommerceView( productSKU, productName, categoryName, price )` - Set the current page view as a product or category page view. When you call `setEcommerceView` it must be followed by a call to `trackPageView` to record the product or category page view. * `addEcommerceItem( productSKU, [productName], [productCategory], [price], [quantity] )` - Add a product into the ecommerce order. Must be called for each product in the order. @@ -115,7 +116,7 @@ You can use these methods to build your own consent form/pages. [Learn more abou Piwik uses first party cookies to keep track of some user information over time. Consideration must be given to retention times and avoiding conflicts with other cookies, trackers, and apps. * `disableCookies()` - Disable all first party cookies. Existing Piwik cookies for this websites will be deleted on the next page view. -* `deleteCookies()` - Delete the tracking cookies currently currently set (this is useful when [creating new visits](https://piwik.org/faq/how-to/#faq_187)) +* `deleteCookies()` - Delete the tracking cookies currently currently set (this is useful when [creating new visits](https://matomo.org/faq/how-to/#faq_187)) * `hasCookies()` - Return whether cookies are enabled and supported by this browser. * `setCookieNamePrefix( prefix )` - the default prefix is '_pk_'. * `setCookieDomain( domain )` - the default is the document domain; if your website can be visited at both www.example.com and example.com, you would use: `tracker.setCookieDomain('.example.com');` or `tracker.setCookieDomain('*.example.com');` @@ -128,17 +129,17 @@ Piwik uses first party cookies to keep track of some user information over time. ### Advanced uses * `addListener( element )` - Add click listener to a specific link element. When clicked, Piwik will log the click automatically. -* `setRequestMethod( method )` - Set the request method to either "GET" or "POST". (The default is "GET".) To use the POST request method, either 1) the Piwik host is the same as the tracked website host (Piwik installed in the same domain as your tracked website), or 2) if Piwik is not installed on the same host as your website, you need to [enable CORS (Cross domain requests) as explained in this FAQ](https://piwik.org/faq/how-to/faq_18694/). +* `setRequestMethod( method )` - Set the request method to either "GET" or "POST". (The default is "GET".) To use the POST request method, either 1) the Piwik host is the same as the tracked website host (Piwik installed in the same domain as your tracked website), or 2) if Piwik is not installed on the same host as your website, you need to [enable CORS (Cross domain requests) as explained in this FAQ](https://matomo.org/faq/how-to/faq_18694/). * `setCustomRequestProcessing( function )` - Set a function that will process the request content. The function will be called once the request (query parameters string) has been prepared, and before the request content is sent. * `setRequestContentType( contentType )` - Set request Content-Type header value. Applicable when "POST" request method is used via `setRequestMethod`. * `disableQueueRequest()` - Disable the feature which groups together multiple tracking requests and send them as a bulk POST request. Disabling this feature is useful when you want to be able to [replay all logs](https://matomo.org/faq/log-analytics-tool/faq_19221/): one must use `disableQueueRequest` to disable this behaviour to later be able to replay logged Matomo logs (otherwise a subset of the requests wouldn't be able to be replayed). -## Unit Tests Covering piwik.js +## Unit Tests Covering matomo.js -The Piwik JavaScript Tracking API is covered by an extensive JavaScript unit test suite to ensure that the code quality is as high as possible, and that we never break this functionality. Tests are written using QUnit. To run the tests, simply checkout the [Piwik Git repository](https://piwik.org/participate/contributing-with-git/) and go to `/path/to/piwik/tests/javascript/`. Tests are run inside your browser. +The Piwik JavaScript Tracking API is covered by an extensive JavaScript unit test suite to ensure that the code quality is as high as possible, and that we never break this functionality. Tests are written using QUnit. To run the tests, simply checkout the [Piwik Git repository](https://matomo.org/participate/contributing-with-git/) and go to `/path/to/matomo/tests/javascript/`. Tests are run inside your browser. -The Piwik JavaScript API has been tested with numerous web browsers. To maximize coverage, we use services like [crossbrowsertesting.com](https://crossbrowsertesting.com/) and [browsershots.org](http://browsershots.org/). +The Piwik JavaScript API has been tested with numerous web browsers. To maximize coverage, we use services like [crossbrowsertesting.com](https://crossbrowsertesting.com/) and [browsershots.org](https://browsershots.org/). -## Minify piwik.js +## Minify matomo.js -The piwik.js is minified to reduce the size that your website visitors will have to download. The YUI Compressor is used to minify the JavaScript ([more information](https://github.com/matomo-org/matomo/blob/master/js/README.md#introduction)). You can find the original non minified version in [/js/piwik.js](https://github.com/matomo-org/matomo/blob/master/js/piwik.js#L1). +The matomo.js is minified to reduce the size that your website visitors will have to download. The YUI Compressor is used to minify the JavaScript ([more information](https://github.com/matomo-org/matomo/blob/master/js/README.md#introduction)). You can find the original non minified version in [/js/piwik.js](https://github.com/matomo-org/matomo/blob/master/js/piwik.js#L1). diff --git a/docs/4.x/translations.md b/docs/4.x/translations.md index ec058abab..32e17aac7 100644 --- a/docs/4.x/translations.md +++ b/docs/4.x/translations.md @@ -54,7 +54,7 @@ To replace a key with translated text, Piwik will look into the JSON file for th ### Reusing translations -As mentioned Piwik comes with quite a lot of translations. You can and should reuse them but you are supposed to be aware that a translation key might be removed or renamed in the future. It is also possible that a translation key was added in a recent version and therefore is not available in older versions of Piwik. We do not currently announce any of such changes. Still, 99% of the translation keys do not change and it is therefore usually a good idea to reuse existing translations. Especially when you or your company would otherwise not be able to provide them. To find any existing translation keys go to Settings => Translation search in your Piwik installation. The menu item will only appear if the [development mode](https://developer.piwik.org/guides/getting-started-part-1#enable-development-mode) is enabled. +As mentioned Piwik comes with quite a lot of translations. You can and should reuse them but you are supposed to be aware that a translation key might be removed or renamed in the future. It is also possible that a translation key was added in a recent version and therefore is not available in older versions of Piwik. We do not currently announce any of such changes. Still, 99% of the translation keys do not change and it is therefore usually a good idea to reuse existing translations. Especially when you or your company would otherwise not be able to provide them. To find any existing translation keys go to Settings => Translation search in your Piwik installation. The menu item will only appear if the [development mode](https://developer.matomo.org/guides/getting-started-part-1#enable-development-mode) is enabled. ## Translations in PHP @@ -67,7 +67,7 @@ $translatedText = Piwik::translate('MyPlugin_BlogPost'); or ```php -$translatedText = Piwik::translate('MyPlugin_MyParagraphWithALink', '', ''); +$translatedText = Piwik::translate('MyPlugin_MyParagraphWithALink', '', ''); // where the key "MyPlugin_MyParagraphWithALink" could look like this: // "My paragraph has a %1$slink%2$s." ``` @@ -83,7 +83,7 @@ To translate text in Twig templates, use the `translate` filter. For example, or ```twig -{{ 'MyPlugin_MyParagraphWithALink'|translate('', '') }} +{{ 'MyPlugin_MyParagraphWithALink'|translate('', '') }} ``` ## Translation in JavaScript @@ -117,15 +117,15 @@ var translatedText = _pk_translate('MyPlugin_BlogPost'); ## Contributing translations to Piwik -Did you know you can contribute [translations](https://piwik.org/translations/) to Piwik? In case you want to improve an existing translation, translate a missing one or add a new language go to [Piwik Translations and sign up for an account](https://www.transifex.com/piwik/piwik/). +Did you know you can contribute [translations](https://matomo.org/translations/) to Piwik? In case you want to improve an existing translation, translate a missing one or add a new language go to [Piwik Translations and sign up for an account](https://www.transifex.com/matomo-org/matomo/). ## Getting translations for your plugin -As long as you are [developing an open source plugin](https://developer.piwik.org/develop) hosted on Github, you may get in touch with us ([translations@matomo.org](mailto:translations@matomo.org?subject=Getting my Piwik plugin translated in other languages)) in order to get your plugin translated by the Piwik translators community. +As long as you are [developing an open source plugin](https://developer.matomo.org/develop) hosted on Github, you may get in touch with us ([translations@matomo.org](mailto:translations@matomo.org?subject=Getting my Piwik plugin translated in other languages)) in order to get your plugin translated by the Piwik translators community. -You will need an account on [Transifex.com](http://transifex.com/). If you use Transifex with a social login, please ensure to set a password in your account settings. This will be required for fetching new translations into your plugin repository. +You will need an account on [Transifex.com](https://transifex.com/). If you use Transifex with a social login, please ensure to set a password in your account settings. This will be required for fetching new translations into your plugin repository. ### Importing your plugin’s strings in the translation platform @@ -133,7 +133,7 @@ While doing the initial setup for your plugin, we will import your english trans ### How to fetch your plugins translations into your repository -As soon as we have set up your plugin within [our Piwik project on Transifex](https://www.transifex.com/projects/p/piwik/) and there are new translations available, you will be able to update your plugin translations using the Piwik console. You will need a locally installed Piwik with [development mode enabled](https://developer.piwik.org/guides/getting-started-part-1#enable-development-mode), and your plugin installed. To update the translations go to the Piwik directory on your development box and execute the following command: +As soon as we have set up your plugin within [our Piwik project on Transifex](https://www.transifex.com/projects/p/matomo-org/) and there are new translations available, you will be able to update your plugin translations using the Piwik console. You will need a locally installed Piwik with [development mode enabled](https://developer.matomo.org/guides/getting-started-part-1#enable-development-mode), and your plugin installed. To update the translations go to the Piwik directory on your development box and execute the following command: ```bash ./console translations:update -u {YourTransifexUserName} -p {YourTransifexPassword} -P {YourPluginName} diff --git a/docs/4.x/views.md b/docs/4.x/views.md index 7f3435b99..9bc107c76 100644 --- a/docs/4.x/views.md +++ b/docs/4.x/views.md @@ -48,4 +48,4 @@ Piwik has a UI demo page available. This page is intended to show all the UI com 1. Go to the Administration page (gear icon) 2. In the navigation menu, under _Development_, select _UI Demo_ -Note: The _Development_ menu section will only appear if the [development mode](https://developer.piwik.org/guides/getting-started-part-1#enable-development-mode) is enabled. +Note: The _Development_ menu section will only appear if the [development mode](https://developer.matomo.org/guides/getting-started-part-1#enable-development-mode) is enabled. diff --git a/docs/4.x/visualizing-report-data.md b/docs/4.x/visualizing-report-data.md index 3e1026d01..0e8c4ef68 100644 --- a/docs/4.x/visualizing-report-data.md +++ b/docs/4.x/visualizing-report-data.md @@ -21,9 +21,9 @@ Users can switch visualizations by clicking on one of the icons displayed below ![](/img/report-visualizations.png) -These icons are called **footer icons**. Not all visualizations have to be available in this manner. For example, the [Visit Log](https://piwik.org/docs/real-time/) uses its own visualization, but since it can only use data from one report (`Live.getLastVisitsDetails`) it is not available in the footer of other reports. +These icons are called **footer icons**. Not all visualizations have to be available in this manner. For example, the [Visit Log](https://matomo.org/docs/real-time/) uses its own visualization, but since it can only use data from one report (`Live.getLastVisitsDetails`) it is not available in the footer of other reports. -To learn more about the controls that surround a visualization in most report displays, [read the user documentation for report visualizations](https://piwik.org/docs/piwik-tour/#a-look-at-a-piwik-report). +To learn more about the controls that surround a visualization in most report displays, [read the user documentation for report visualizations](https://matomo.org/docs/matomo-tour/#a-look-at-a-piwik-report). ### Using ViewDataTable @@ -123,7 +123,7 @@ public function addWidgets() Piwik users will then be able to see and select **myReport** in the widget selector. -*Note: Any controller method can be embedded in the dashboard, not just reports. So if you have a popup that you'd like to make available as a dashboard widget, you can use [WidgetsList.addWidgets](/api-reference/events#widgetslistaddwidgets) to do so. This is exactly how we made the [Visitor Profile](https://piwik.org/docs/user-profile/) available in the dashboard.* +*Note: Any controller method can be embedded in the dashboard, not just reports. So if you have a popup that you'd like to make available as a dashboard widget, you can use [WidgetsList.addWidgets](/api-reference/events#widgetslistaddwidgets) to do so. This is exactly how we made the [Visitor Profile](https://matomo.org/docs/user-profile/) available in the dashboard.* ## Core report visualizations @@ -144,7 +144,7 @@ You can use these visualizations when creating [ViewDataTable](/api-reference/Pi Plugins can provide their own visualizations, either for use within the plugin or as a new visualization that can be applied to any report. -The [Treemap Visualization](https://plugins.piwik.org/TreemapVisualization) plugin is an example of a plugin providing a visualization that can be used for any report. +The [Treemap Visualization](https://plugins.matomo.org/TreemapVisualization) plugin is an example of a plugin providing a visualization that can be used for any report. ### Extending ViewDataTable @@ -217,7 +217,7 @@ Visualizations can also create their own [RequestConfig](/api-reference/Piwik/Vi If needed, custom visualizations can alter what data is loaded by the base `ViewDataTable` class. -The evolution graph visualization does this to get reports for the last N periods so it can display data over time. The [treemap visualization](https://plugins.piwik.org/TreemapVisualization) does this to get data for last period so the percent change of each row can be displayed. +The evolution graph visualization does this to get reports for the last N periods so it can display data over time. The [treemap visualization](https://plugins.matomo.org/TreemapVisualization) does this to get data for last period so the percent change of each row can be displayed. To change what data is loaded, visualizations can alter the request using the [`$request_parameters_to_modify`](/api-reference/Piwik/ViewDataTable/RequestConfig#request_parameters_to_modify) property. This can be done in the [`Visualization::beforeLoadDataTable()`](/api-reference/Piwik/Plugin/Visualization#beforeloaddatatable) method. For example: diff --git a/docs/4.x/working-with-piwiks-ui.md b/docs/4.x/working-with-piwiks-ui.md index 86aca3aca..f7b5c698c 100644 --- a/docs/4.x/working-with-piwiks-ui.md +++ b/docs/4.x/working-with-piwiks-ui.md @@ -15,7 +15,7 @@ Piwik uses the following JavaScript libraries: * [jQuery](https://jquery.com/) and [jQuery UI](https://jqueryui.com/) * [AngularJS](https://angularjs.org/) -* [jqPlot](http://www.jqplot.com/) +* [jqPlot](https://www.jqplot.com/) * A couple of other libraries are used see our [bower dependencies](https://github.com/matomo-org/matomo/blob/master/bower.json) **Include new JS libraries only if they are vital to your plugin.** If many plugins decide to use a custom library, the UI will slow down and plugins might get problems when different plugins load different versions of those libraries. @@ -47,7 +47,7 @@ public function getJavaScriptFiles(&$files) ### Asset merging and compiling -In production environments, Piwik will concatenate all JavaScript files into one and minify it. [LESS](http://lesscss.org/) files will be compiled into CSS and merged into one CSS file. Piwik does not merge and minify JavaScript and CSS files on every request as it takes a long time to do this. They are only merged on certain events, such as when enabling a new plugin. +In production environments, Piwik will concatenate all JavaScript files into one and minify it. [LESS](https://lesscss.org/) files will be compiled into CSS and merged into one CSS file. Piwik does not merge and minify JavaScript and CSS files on every request as it takes a long time to do this. They are only merged on certain events, such as when enabling a new plugin. To make sure your changes will be actually visible and executed you need to enable the development mode in case you have not done yet: @@ -201,6 +201,6 @@ For example: ## Learn more * To learn **about creating new report visualizations** read our [Visualizing Report Data](/guides/visualizing-report-data) guide. -* To learn **more about the asset merging system** read this [blog post](https://piwik.org/blog/2010/07/making-piwik-ui-faster/) by the system's author. +* To learn **more about the asset merging system** read this [blog post](https://matomo.org/blog/2010/07/making-piwik-ui-faster/) by the system's author. * To learn **more about theming** read our [Theming](/guides/theming) guide. * To learn **more about UI components and styles** read our [Views](/guides/views) guide.