Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/socialgouv/matomo-next
Matomo for Next.js applications
https://github.com/socialgouv/matomo-next
analytics matomo nextjs
Last synced: about 7 hours ago
JSON representation
Matomo for Next.js applications
- Host: GitHub
- URL: https://github.com/socialgouv/matomo-next
- Owner: SocialGouv
- License: apache-2.0
- Created: 2020-05-15T07:17:10.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-04-10T17:53:35.000Z (7 months ago)
- Last Synced: 2024-04-14T11:31:51.949Z (7 months ago)
- Topics: analytics, matomo, nextjs
- Language: TypeScript
- Homepage:
- Size: 620 KB
- Stars: 146
- Watchers: 6
- Forks: 20
- Open Issues: 25
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
Matomo Next
Matomo analytics for Next.js applications
- Basic SPA Matomo setup
- Will track `next/router` route changes `routeChangeComplete` event
- ⚠️ Notes for [Next.js app router](https://github.com/SocialGouv/matomo-next/issues/99)
## Usage
Add the `init` call in your `_app.js` :
```jsx
import React, { useEffect } from "react";
import App from "next/app";
import { init } from "@socialgouv/matomo-next";
const MATOMO_URL = process.env.NEXT_PUBLIC_MATOMO_URL;
const MATOMO_SITE_ID = process.env.NEXT_PUBLIC_MATOMO_SITE_ID;
function MyApp({ Component, pageProps }) {
useEffect(() => {
init({ url: MATOMO_URL, siteId: MATOMO_SITE_ID });
}, []);
return ;
}
export default MyApp;
```
Will track routes changes by default.
### Exclude tracking some routes :
This wont track `/login.php` or any url containing `?token=`.
```js
init({
url: MATOMO_URL,
siteId: MATOMO_SITE_ID,
excludeUrlsPatterns: [/^\/login.php/, /\?token=.+/],
});
```
### Disable cookies :
To disable cookies (for better GDPR compliance) set the `disableCookies` flag to `true`.
```js
init({
url: MATOMO_URL,
siteId: MATOMO_SITE_ID,
disableCookies: true,
});
```
### Track additional events :
```js
import { push } from "@socialgouv/matomo-next";
// track some events
push(["trackEvent", "contact", "click phone"]);
```
### Content-Security-Policy
#### [Nonce](https://developer.mozilla.org/fr/docs/Web/HTML/Global_attributes/nonce)
If you use a `Content-Security-Policy` header with a `nonce` attribute, you can pass it to the `init` function to allow the script to be executed.
```js
init({
url: MATOMO_URL,
siteId: MATOMO_SITE_ID,
nonce: "123456789",
})
```
#### [Trusted Types](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/trusted-types)
As the `matomo-next` injects a matomo script, if you use strict Trusted Types, you need to allow the `script` tag to be created by adding our policy name to your `trusted types` directive.
```
Content-Security-Policy: require-trusted-types-for 'script'; trusted-types matomo-next;
```
You can set a custom policy name by passing it to the `init` function.
```js
init({
url: MATOMO_URL,
siteId: MATOMO_SITE_ID,
trustedPolicyName: "your-custom-policy-name",
})
```
### Extensibility
The function has three optional callback properties that allow for custom behavior to be added:
- `onRouteChangeStart(path: string) => void`: This callback is triggered when the route is about to change with Next Router event `routeChangeStart`. It receives the new path as a parameter.
- `onRouteChangeComplete`: This callback is triggered when the route change is complete with Next Router event `routeChangeComplete`. It receives the new path as a parameter.
- `onInitialization`: This callback is triggered when the function is first initialized. It does not receive any parameters. **It could be useful to use it if you want to add parameter to Matomo when the page is render the first time.**
- `onScriptLoadingError`: This callback is triggered when the script does not load. It does not receive any parameters. useful to detect ad-blockers.
## Tests
```
init
✓ should create a js tag and initialize (7 ms)
✓ should NOT create events when url is not provided (9 ms)
push
✓ should append data to window._paq (1 ms)
✓ should append dimensions data to window._paq (1 ms)
onInitialization
✓ should work if the surcharge of the operator (1 ms)
router.routeChangeStart event
✓ should setReferrerUrl and setCustomUrl on route change start (1 ms)
✓ should setReferrerUrl and setCustomUrl on route change start and handle hashtag (by removing it)
✓ should use previousPath as referer on consecutive route change (1 ms)
✓ should work if the surcharge of the operator (3 ms)
router.routeChangeComplete event
✓ should trackPageView with correct title on route change (3 ms)
✓ should use previousPath as referer on consecutive route change (2 ms)
✓ should track route as search in /recherche (1 ms)
✓ should track route as search in /search (2 ms)
✓ should work if the surcharge of the operator (2 ms)
excludeUrlsPatterns
✓ should excluded login.php and token variables (2 ms)
✓ should exclude initial page tracking (3 ms)
✓ should track initial page if not excluded (2 ms)
disableCookies
✓ should NOT append disableCookies to window._paq by default (1 ms)
✓ should append disableCookies to window._paq (1 ms)
```