# @datapunt/matomo-tracker-react

> Matomo tracker for react projects

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

## Install

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

## 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-22 |
| Weekly downloads | 0 |
| License | MPL-2.0 |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 50 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 142 |
| Author | Datapunt Amsterdam |
| Maintainers | chrisvanmook, datapunt-admin |
| Keywords | matomo, piwik, tracking, analytics, react |

## Links

- npm: https://www.npmjs.com/package/@datapunt/matomo-tracker-react
- 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-react

## Dependencies (1)

- [@datapunt/matomo-tracker-js](https://npm.io/package/@datapunt/matomo-tracker-js.md) ^0.5.1

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K 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
- … 6 more at https://npm.io/package/@datapunt/matomo-tracker-react/versions

## README

# Matomo Tracker (React)

Stand alone library for using Matamo tracking in React projects

## Installation

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

```tsx
import { MatomoProvider, createInstance } from '@datapunt/matomo-tracker-react'

const instance = createInstance({
  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'
  }
})

ReactDOM.render(
  <MatomoProvider value={instance}>
    <MyApp />
  </MatomoProvider>,
)
```

After wrapping your application with the `MatomoProvider` you can use the `useMatomo` hook to track your application from anywhere within the MatomoProvider component tree:

```tsx
import React from 'react'
import { useMatomo } from '@datapunt/matomo-tracker-react'

const MyPage = () => {
  const { trackPageView, trackEvent } = useMatomo()

  // Track page view
  React.useEffect(() => {
    trackPageView()
  }, [])

  const handleOnClick = () => {
    // Track click on button
    trackEvent({ category: 'sample-page', action: 'click-event' })
  }

  return (
    <button type="button" onClick={handleOnClick}>
      Click me
    </button>
  )
}
```

## Advanced usage

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:

```tsx
import React from 'react'
import { useMatomo } from '@datapunt/matomo-tracker-react'

const MyPage = () => {
  const { trackPageView, trackEvent } = useMatomo()

  // Track page view
  React.useEffect(() => {
    trackPageView({
      documentTitle: 'Page title', // optional
      href: 'https://LINK.TO.PAGE', // optional
      customDimensions: [
        {
          id: 1,
          value: 'loggedIn',
        },
      ], // optional
    })
  }, [])

  const handleOnClick = () => {
    // Track click on button
    trackEvent({ category: 'sample-page', action: 'click-event' })
  }

  return (
    <button type="button" onClick={handleOnClick}>
      Click me
    </button>
  )
}
```

And you can do the same for the `trackEvent` method:

```tsx
import React from 'react'
import { useMatomo } from '@datapunt/matomo-tracker-react'

const MyPage = () => {
  const { trackEvent } = useMatomo()

  const handleOnClick = () => {
    // Track click on button
    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
    })
  }

  return (
    <button type="button" onClick={handleOnClick}>
      Click me
    </button>
  )
}
```

The `useMatomo` hook also exposes the following methods:
* `trackEvents()`
* `trackSiteSearch()`
* `trackLink()`
* `pushInstruction()`

For example, the `pushInstruction()` function can be used to push instructions to Matomo for execution. This
is equivalent to pushing entries into the `_paq` array.


```javascript
const { pushInstruction } = useMatomo();
pushInstruction('setUserId', 'USER_ID_HERE');
```

## SPA Link Tracking

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 `linkTracking` option on the instance passed to the provider to prevent Matomo from catching some link clicks:

```tsx
import { MatomoProvider, createInstance, useMatomo } from '@datapunt/matomo-tracker-react'

const instance = createInstance({
  urlBase: "https://LINK.TO.DOMAIN",
  linkTracking: false // Important!
});

ReactDOM.render(
  <MatomoProvider value={instance}>
    <MyApp />
  </MatomoProvider>
)

const MyApp = () => {
  const { enableLinkTracking } = useMatomo()

  enableLinkTracking()

  return (
    // Render components
  )
}

```

## References

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

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