{"_id":"@antoine-giret/matomo-tracker-react","_rev":"1-c7e0d759f668e9da0526e866989a9efc","name":"@antoine-giret/matomo-tracker-react","dist-tags":{"latest":"0.5.2"},"versions":{"0.5.2":{"name":"@antoine-giret/matomo-tracker-react","version":"0.5.2","description":"Matomo tracker for react projects","main":"lib/index.js","module":"es/index.js","license":"MPL-2.0","author":{"name":"Datapunt Amsterdam"},"homepage":"https://github.com/Amsterdam/matomo-tracker#readme","repository":{"type":"git","url":"git+https://github.com/Amsterdam/matomo-tracker.git","directory":"packages/react"},"bugs":{"url":"https://github.com/Amsterdam/matomo-tracker/issues"},"sideEffects":false,"contributors":[{"name":"Chris van Mook","email":"chrisvanmook@gmail.com"},{"name":"Jon Koops","email":"jonkoops@gmail.com"}],"keywords":["matomo","piwik","tracking","analytics","react"],"publishConfig":{"access":"public"},"dependencies":{"@datapunt/matomo-tracker-js":"^0.5.1"},"peerDependencies":{"react":">= 16.8.0"},"gitHead":"fa836495e5a7e0686787edb7e3dfb8da914069e3","_id":"@antoine-giret/matomo-tracker-react@0.5.2","_nodeVersion":"16.13.2","_npmVersion":"lerna/4.0.0/node@v16.13.2+arm64 (darwin)","dist":{"integrity":"sha512-1LyR78WTcSZCwQtaUYb1ld+tHke3joag4u0g3LVa8zJK3dCfLfhSrv0FVFWho3Gb9bme9BcCS6Ov169qVVMCHw==","shasum":"7027fe21b0652852aa9e5500a7b9b40af8941c18","tarball":"https://registry.npmjs.org/@antoine-giret/matomo-tracker-react/-/matomo-tracker-react-0.5.2.tgz","fileCount":67,"unpackedSize":58812,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v4.10.10\r\nComment: https://openpgpjs.org\r\n\r\nwsFzBAEBCAAGBQJiFlyaACEJED1NWxICdlZqFiEECWMYAoorWMhJKdjhPU1b\r\nEgJ2VmrAug/+Psh0x4g5H/CpuB4tcCV0tn27jhzzbygR1wYS4Vtz0xfzXVL3\r\nVJuLk18NAyU5qlheQP2VZB9WBh28t9+LaBxQo8yw8myLM/tpJ1SPugIUuV8I\r\nZtUDuBRTPRKKAakqc19hKeP6uOxv+MmjG3965o19OiKKUHUOln2z4esA5nkz\r\n68so9ZG/oX8PNOJ6iOZlzTW6pjegVmvSzx7fU5ebFClP2cl40DUCMDEyF3o5\r\nb+VEw4HdEu/fJVZL9w02kOtxUXgVwY99S9XyaEo4+LbP5VAxP0PbGjNBZpVG\r\n6rHMBHboQYnOazycaGS1zZnoe1ZdF01E28/44bo9Hi5XiskqmFqZg//Ge9bz\r\nrVslKSJlTwUuDE2C3JDlTQt600eD+GfSU/eCEpUmfxURxC91ooeLqQySOZE9\r\naPwlStIyQXC/WlXrNfXYp4WlUw4Xx/Uyqy1NdNzSHjIfiofOdw9sPib2ZuvW\r\nHYpB1HsAaez1FRvjRVp0MnnSe6OQcQ1goPI6SYTRq+yRkNHfr8JjdGbALfre\r\nmaCrV3q3EyWBlS6/2dgObAOpIePUAzPS400w93xBi+CLZWi4HOzaMYoAQw7m\r\ny//Ynop5PmRBlii6YVGb9bK9lUYDyEQ7wO2nSmTRKw61xJs/kVmjtnLBt4LH\r\nSzW571O3UB00C3vdp5o+UXF/SNjvWKSpqRw=\r\n=64vS\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQC6xC+lXPGN+nAeoodh80nbE+mv0SwrGU0O4X2+9fztmwIhAMPqbTaqha9NiseXSSOmE85sW4tyEbQN9cAm4fuV7e6u"}]},"_npmUser":{"name":"antoine-giret","email":"ant.giret@gmail.com"},"directories":{},"maintainers":[{"name":"antoine-giret","email":"ant.giret@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/matomo-tracker-react_0.5.2_1645632665842_0.15930336907888032"},"_hasShrinkwrap":false}},"time":{"created":"2022-02-23T16:11:05.781Z","0.5.2":"2022-02-23T16:11:06.006Z","modified":"2022-04-04T14:22:48.955Z"},"maintainers":[{"name":"antoine-giret","email":"ant.giret@gmail.com"}],"description":"Matomo tracker for react projects","homepage":"https://github.com/Amsterdam/matomo-tracker#readme","keywords":["matomo","piwik","tracking","analytics","react"],"repository":{"type":"git","url":"git+https://github.com/Amsterdam/matomo-tracker.git","directory":"packages/react"},"contributors":[{"name":"Chris van Mook","email":"chrisvanmook@gmail.com"},{"name":"Jon Koops","email":"jonkoops@gmail.com"}],"author":{"name":"Datapunt Amsterdam"},"bugs":{"url":"https://github.com/Amsterdam/matomo-tracker/issues"},"license":"MPL-2.0","readme":"# Matomo Tracker (React)\n\nStand alone library for using Matamo tracking in React projects\n\n## Installation\n\n```sh\nnpm install @datapunt/matomo-tracker-react\n```\n\n## Usage\n\nBefore 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.\n\n```tsx\nimport { MatomoProvider, createInstance } from '@datapunt/matomo-tracker-react'\n\nconst instance = createInstance({\n  urlBase: 'https://LINK.TO.DOMAIN',\n  siteId: 3,\n  userId: 'UID76903202', // optional, default value: `undefined`.\n  trackerUrl: 'https://LINK.TO.DOMAIN/tracking.php', // optional, default value: `${urlBase}matomo.php`\n  srcUrl: 'https://LINK.TO.DOMAIN/tracking.js', // optional, default value: `${urlBase}matomo.js`\n  disabled: false, // optional, false by default. Makes all tracking calls no-ops if set to true.\n  heartBeat: { // optional, enabled by default\n    active: true, // optional, default value: true\n    seconds: 10 // optional, default value: `15\n  },\n  linkTracking: false, // optional, default value: true\n  configurations: { // optional, default value: {}\n    // any valid matomo configuration, all below are optional\n    disableCookies: true,\n    setSecureCookie: true,\n    setRequestMethod: 'POST'\n  }\n})\n\nReactDOM.render(\n  <MatomoProvider value={instance}>\n    <MyApp />\n  </MatomoProvider>,\n)\n```\n\nAfter wrapping your application with the `MatomoProvider` you can use the `useMatomo` hook to track your application from anywhere within the MatomoProvider component tree:\n\n```tsx\nimport React from 'react'\nimport { useMatomo } from '@datapunt/matomo-tracker-react'\n\nconst MyPage = () => {\n  const { trackPageView, trackEvent } = useMatomo()\n\n  // Track page view\n  React.useEffect(() => {\n    trackPageView()\n  }, [])\n\n  const handleOnClick = () => {\n    // Track click on button\n    trackEvent({ category: 'sample-page', action: 'click-event' })\n  }\n\n  return (\n    <button type=\"button\" onClick={handleOnClick}>\n      Click me\n    </button>\n  )\n}\n```\n\n## Advanced usage\n\nBy 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:\n\n```tsx\nimport React from 'react'\nimport { useMatomo } from '@datapunt/matomo-tracker-react'\n\nconst MyPage = () => {\n  const { trackPageView, trackEvent } = useMatomo()\n\n  // Track page view\n  React.useEffect(() => {\n    trackPageView({\n      documentTitle: 'Page title', // optional\n      href: 'https://LINK.TO.PAGE', // optional\n      customDimensions: [\n        {\n          id: 1,\n          value: 'loggedIn',\n        },\n      ], // optional\n    })\n  }, [])\n\n  const handleOnClick = () => {\n    // Track click on button\n    trackEvent({ category: 'sample-page', action: 'click-event' })\n  }\n\n  return (\n    <button type=\"button\" onClick={handleOnClick}>\n      Click me\n    </button>\n  )\n}\n```\n\nAnd you can do the same for the `trackEvent` method:\n\n```tsx\nimport React from 'react'\nimport { useMatomo } from '@datapunt/matomo-tracker-react'\n\nconst MyPage = () => {\n  const { trackEvent } = useMatomo()\n\n  const handleOnClick = () => {\n    // Track click on button\n    trackEvent({\n      category: 'sample-page',\n      action: 'click-event',\n      name: 'test', // optional\n      value: 123, // optional, numerical value\n      documentTitle: 'Page title', // optional\n      href: 'https://LINK.TO.PAGE', // optional\n      customDimensions: [\n        {\n          id: 1,\n          value: 'loggedIn',\n        },\n      ], // optional\n    })\n  }\n\n  return (\n    <button type=\"button\" onClick={handleOnClick}>\n      Click me\n    </button>\n  )\n}\n```\n\nThe `useMatomo` hook also exposes the following methods:\n* `trackEvents()`\n* `trackSiteSearch()`\n* `trackLink()`\n* `pushInstruction()`\n\nFor example, the `pushInstruction()` function can be used to push instructions to Matomo for execution. This\nis equivalent to pushing entries into the `_paq` array.\n\n\n```javascript\nconst { pushInstruction } = useMatomo();\npushInstruction('setUserId', 'USER_ID_HERE');\n```\n\n## SPA Link Tracking\n\nMatomo 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:\n\n```tsx\nimport { MatomoProvider, createInstance, useMatomo } from '@datapunt/matomo-tracker-react'\n\nconst instance = createInstance({\n  urlBase: \"https://LINK.TO.DOMAIN\",\n  linkTracking: false // Important!\n});\n\nReactDOM.render(\n  <MatomoProvider value={instance}>\n    <MyApp />\n  </MatomoProvider>\n)\n\nconst MyApp = () => {\n  const { enableLinkTracking } = useMatomo()\n\n  enableLinkTracking()\n\n  return (\n    // Render components\n  )\n}\n\n```\n\n## References\n\n- [Matomo JavaScript Tracking Guide](https://developer.matomo.org/guides/tracking-javascript-guide)\n","readmeFilename":"README.md"}