# @datapunt/matomo-tracker-js

> Matomo tracker for frontend projects

Latest version **0.5.1** (published 2021-08-11) · MPL-2.0 license · 0 weekly downloads

## Install

```sh
npm install @datapunt/matomo-tracker-js
pnpm add @datapunt/matomo-tracker-js
yarn add @datapunt/matomo-tracker-js
bun add @datapunt/matomo-tracker-js
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.5.1 |
| Published | 2021-08-11 |
| First published | 2019-08-15 |
| Weekly downloads | 0 |
| License | MPL-2.0 |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 78.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 142 |
| Author | Datapunt Amsterdam |
| Maintainers | chrisvanmook |
| Keywords | matomo, piwik, tracking, analytics, client |

## Links

- npm: https://www.npmjs.com/package/@datapunt/matomo-tracker-js
- Repository: https://github.com/Amsterdam/matomo-tracker
- Homepage: https://github.com/Amsterdam/matomo-tracker#readme
- Issues: https://github.com/Amsterdam/matomo-tracker/issues
- npm.io page: https://npm.io/package/@datapunt/matomo-tracker-js

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 0.5.1 (latest) — 2021-08-11
- 0.5.0 — 2021-08-04
- 0.4.1-0.5.0-alpha.1.0 — 2021-08-04
- 0.4.0 — 2021-02-15
- 0.3.1 — 2020-10-22
- 0.3.0 — 2020-10-21
- 0.2.1 — 2020-09-04
- 0.2.0 — 2020-08-31
- 0.1.5 — 2020-05-31
- 0.1.4 — 2020-05-08
- 0.1.3 — 2020-05-08
- 0.1.2 — 2020-04-28
- 0.1.1 — 2020-02-24
- 0.1.0 — 2020-02-19
- 0.0.16 — 2020-01-07
- … 13 more at https://npm.io/package/@datapunt/matomo-tracker-js/versions

## README

# Matomo Tracker (JavaScript)

Stand alone library for using Matamo tracking in frontend projects

## Installation

```sh
npm install @datapunt/matomo-tracker-js
```

## Usage

Before you're able to use this Matomo Tracker you need to initialize Matomo with your project specific details.

**Initialize:**

```ts
import MatomoTracker from '@datapunt/matomo-tracker-js'

const tracker = new MatomoTracker({
  urlBase: 'https://LINK.TO.DOMAIN',
  siteId: 3,
  userId: 'UID76903202', // optional, default value: `undefined`.
  trackerUrl: 'https://LINK.TO.DOMAIN/tracking.php', // optional, default value: `${urlBase}matomo.php`
  srcUrl: 'https://LINK.TO.DOMAIN/tracking.js', // optional, default value: `${urlBase}matomo.js`
  disabled: false, // optional, false by default. Makes all tracking calls no-ops if set to true.
  heartBeat: { // optional, enabled by default
    active: true, // optional, default value: true
    seconds: 10 // optional, default value: `15
  },
  linkTracking: false, // optional, default value: true
  configurations: { // optional, default value: {}
    // any valid matomo configuration, all below are optional
    disableCookies: true,
    setSecureCookie: true,
    setRequestMethod: 'POST'
  }
})
```

After initialization you can use the Matomo Tracker to track events and page views like this:

```ts
import MatomoTracker from '@datapunt/matomo-tracker-js'

const tracker = new MatomoTracker({
  /* setup */
})

tracker.trackPageView()

tracker.trackEvent({
  category: 'sample-page',
  action: 'click-event',
  name: 'test', // optional
  value: 123, // optional, numerical value
})

tracker.trackLink({
  href: 'https://link-to-other-website.org',
})
```

## Advanced usage

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:

```ts
import MatomoTracker from '@datapunt/matomo-tracker-js'

const tracker = new MatomoTracker({
  /* setup */
})

tracker.trackPageView({
  documentTitle: 'Page title', // optional
  href: 'https://LINK.TO.PAGE', // optional
  customDimensions: [
    {
      id: 1,
      value: 'loggedIn',
    },
  ], // optional
})

tracker.trackEvent({
  category: 'sample-page',
  action: 'click-event',
  name: 'test', // optional
  value: 123, // optional, numerical value
  documentTitle: 'Page title', // optional
  href: 'https://LINK.TO.PAGE', // optional
  customDimensions: [
    {
      id: 1,
      value: 'loggedIn',
    },
  ], // optional
})

tracker.trackLink({
  href: 'https://link-to-your-file.pdf',
  linkType: 'download', // optional, default value 'link'
})
```

Next to the tracking of events, this project also supports tracking site searches:

```ts
import MatomoTracker from '@datapunt/matomo-tracker-js'

const tracker = new MatomoTracker({
  /* setup */
})

tracker.trackSiteSearch({
  keyword: 'test',
  category: 'blog', // optional
  count: 4, // optional
  documentTitle: 'Page title', // optional
  href: 'https://LINK.TO.PAGE', // optional
  customDimensions: [
    {
      id: 1,
      value: 'loggedIn',
    },
  ], // optional
})
```

Or if you want to stay away from inline JavaScript events, this project can be used to track events from buttons with data attributes:

**HTML5 data-attributes**

```html
<button
  data-matomo-event="click"
  data-matomo-category="sample-page"
  data-matomo-action="click-event"
  data-matomo-name="test" // optional
  data-matomo-value="123" // optional, numerical value
  type="button">
  Track me!
</button>
```

```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

- [Matomo JavaScript Tracking Guide](https://developer.matomo.org/guides/tracking-javascript-guide)

---
_Source: https://npm.io/package/@datapunt/matomo-tracker-js · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
