From 7d17c79fb0cd15ae7c19e279d9b42bf3f89d1ee7 Mon Sep 17 00:00:00 2001 From: Jon Koops Date: Mon, 3 Aug 2020 17:28:42 +0200 Subject: [PATCH] Remove global MatomoTracker from the window object --- CHANGELOG.md | 1 + packages/js/README.md | 110 +++++++++++++-------------------- packages/js/example/index.html | 64 ------------------- packages/js/src/index.ts | 5 -- packages/react/README.md | 15 ++--- 5 files changed, 51 insertions(+), 144 deletions(-) delete mode 100644 packages/js/example/index.html diff --git a/CHANGELOG.md b/CHANGELOG.md index 93c487c3..976023a4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,7 @@ Prefix the change with one of these keywords: - _Added_: include `configurations` in the `MatomoTracker.initialize` params - _Added_: add a generic `pushInstruction` method to pass instructions to Matomo +- _Removed_: removed the `window.MatomoTracker` global ## [0.1.5] diff --git a/packages/js/README.md b/packages/js/README.md index 1936a334..f5eb86ae 100644 --- a/packages/js/README.md +++ b/packages/js/README.md @@ -4,31 +4,8 @@ Stand alone library for using Matamo tracking in frontend projects ## Installation -Matomo Tracker can be used in two ways: - -1. Installing with npm: `npm i --save @datapunt/matomo-tracker-js` or yarn `yarn add -S @datapunt/matomo-tracker-js` - -```js -import MatomoTracker from '@datapunt/matomo-tracker-js' - -const MatomoInstance = new window.MatomoTracker({ ... }) -``` - -2. By downloading the `bundle.min.js` from this repo and load it in your html as a script: - -```html - - +```sh +npm install @datapunt/matomo-tracker-js ``` ## Usage @@ -37,8 +14,10 @@ Before you're able to use this Matomo Tracker you need to initialize Matomo with **Initialize:** -```js -const MatomoInstance = new window.MatomoTracker({ +```ts +import MatomoTracker from '@datapunt/matomo-tracker-js' + +const tracker = new MatomoTracker({ urlBase: 'https://LINK.TO.DOMAIN', siteId: 3, // optional, default value: `1` userId: 'UID76903202', // optional, default value: `undefined`. @@ -60,23 +39,23 @@ const MatomoInstance = new window.MatomoTracker({ After initialization you can use the Matomo Tracker to track events and page views like this: -```js +```ts import MatomoTracker from '@datapunt/matomo-tracker-js' -const MatomoInstance = new MatomoTracker({ +const tracker = new MatomoTracker({ /* setup */ }) -MatomoInstance.trackPageView() +tracker.trackPageView() -MatomoInstance.trackEvent({ +tracker.trackEvent({ category: 'sample-page', action: 'click-event', name: 'test', // optional value: 123, // optional, numerical value }) -MatomoInstance.trackLink({ +tracker.trackLink({ href: 'https://link-to-other-website.org', }) ``` @@ -85,14 +64,14 @@ MatomoInstance.trackLink({ By default the Matomo Tracker will send the window's document title and location, but you're able to send your own values. Also, [custom dimensions](https://matomo.org/docs/custom-dimensions/) can be used: -```js +```ts import MatomoTracker from '@datapunt/matomo-tracker-js' -const MatomoInstance = new MatomoTracker({ +const tracker = new MatomoTracker({ /* setup */ }) -MatomoInstance.trackPageView({ +tracker.trackPageView({ documentTitle: 'Page title', // optional href: 'https://LINK.TO.PAGE', // optional customDimensions: [ @@ -103,7 +82,7 @@ MatomoInstance.trackPageView({ ], // optional }) -MatomoInstance.trackEvent({ +tracker.trackEvent({ category: 'sample-page', action: 'click-event', name: 'test', // optional @@ -118,7 +97,7 @@ MatomoInstance.trackEvent({ ], // optional }) -MatomoInstance.trackLink({ +tracker.trackLink({ href: 'https://link-to-your-file.pdf', linkType: 'download', // optional, default value 'link' }) @@ -126,14 +105,14 @@ MatomoInstance.trackLink({ Next to the tracking of events, this project also supports tracking site searches: -```js +```ts import MatomoTracker from '@datapunt/matomo-tracker-js' -const MatomoInstance = new MatomoTracker({ +const tracker = new MatomoTracker({ /* setup */ }) -MatomoInstance.trackSiteSearch({ +tracker.trackSiteSearch({ keyword: 'test', category: 'blog', // optional count: 4, // optional @@ -153,34 +132,29 @@ Or if you want to stay away from inline JavaScript events, this project can be u **HTML5 data-attributes** ```html - - - - - - - - - - + +``` + +```ts +import MatomoTracker from '@datapunt/matomo-tracker-js' + +const tracker = new MatomoTracker({ + /* setup */ +}) + +// Load the event listeners +tracker.trackEvents() + +// Track page views +tracker.trackPageView() ``` ## References diff --git a/packages/js/example/index.html b/packages/js/example/index.html deleted file mode 100644 index 718df485..00000000 --- a/packages/js/example/index.html +++ /dev/null @@ -1,64 +0,0 @@ - - - - - - - Document - - - - - - -
- - -
- - - - - diff --git a/packages/js/src/index.ts b/packages/js/src/index.ts index 62826964..7396c45f 100644 --- a/packages/js/src/index.ts +++ b/packages/js/src/index.ts @@ -4,14 +4,9 @@ import * as types from './types' declare global { interface Window { _paq: [string, ...any[]][] - MatomoTracker: typeof MatomoTracker } } -if (typeof window !== 'undefined') { - window.MatomoTracker = MatomoTracker -} - export default MatomoTracker export { types } diff --git a/packages/react/README.md b/packages/react/README.md index 047a8da0..6f041a56 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -4,13 +4,15 @@ Stand alone library for using Matamo tracking in React projects ## Installation -Installing with npm: `npm i --save @datapunt/matomo-tracker-react` or yarn `yarn add @datapunt/matomo-tracker-react` +```sh +npm install @datapunt/matomo-tracker-react +``` ## Usage Before you're able to use this Matomo Tracker you need to create a Matomo instance with your project specific details, and wrap your application with the `MatomoProvider` that this package exposes. -```js +```tsx import { MatomoProvider, createInstance } from '@datapunt/matomo-tracker-react' const instance = createInstance({ @@ -41,7 +43,7 @@ ReactDOM.render( After wrapping your application with the `MatomoProvider` you can use the `useMatomo` hook to track your application from anywhere within the MatomoProvider component tree: -```js +```tsx import React from 'react' import { useMatomo } from '@datapunt/matomo-tracker-react' @@ -70,7 +72,7 @@ const MyPage = () => { By default the Matomo Tracker will send the window's document title and location, or send your own values. Also, [custom dimensions](https://matomo.org/docs/custom-dimensions/) can be used: -```js +```tsx import React from 'react' import { useMatomo } from '@datapunt/matomo-tracker-react' @@ -106,7 +108,7 @@ const MyPage = () => { And you can do the same for the `trackEvent` method: -```js +```tsx import React from 'react' import { useMatomo } from '@datapunt/matomo-tracker-react' @@ -143,7 +145,7 @@ const MyPage = () => { Matomo provides the option to track outbound link, however, this implementation is flaky for a SPA (Single Page Application) **without** SSR (Server Side Rendering) across different versions of Matomo. Therefore you can use the `enableLinkTracking` method to listen to outbound clicks on anchor elements. This method should be placed on a component directly below your `MatomoProvider` on a component that's rendered on every page view. Also, make sure to disable the `enableLinkTracking` option on the instance passed to the provider to prevent Matomo from catching some link clicks: -```js +```tsx import { MatomoProvider, createInstance } from '@datapunt/matomo-tracker-react' const instance = createInstance({ @@ -172,4 +174,3 @@ const MyApp = () => { ## References - [Matomo JavaScript Tracking Guide](https://developer.matomo.org/guides/tracking-javascript-guide) -```