{"_id":"@airsoko/next-analytics","name":"@airsoko/next-analytics","dist-tags":{"latest":"0.0.1"},"versions":{"0.0.1":{"name":"@airsoko/next-analytics","version":"0.0.1","description":"This npm package provides utility functions and TypeScript types for the Airsoko API.","author":{"name":"macive"},"private":false,"engines":{"node":">=14"},"license":"UNLICENSED","main":"./dist/index.js","types":"./dist/types/index.d.ts","scripts":{"prebuild":"yarn clean","build-minify":"tsc --declaration  && npm run minify","minify":"jsmin -o test.min.js dist/index.js","build":"tsc --build","format":"prettier --write \"src/**/*.ts\"","dev":"tsc --watch","clean":"rimraf dist && rimraf .turbo && rimraf node_modules","preLaunch":"tsc --build"},"dependencies":{"jsmin":"^1.0.1"},"devDependencies":{"@airsoko/tsconfig":"*"},"publishConfig":{"access":"public"},"_id":"@airsoko/next-analytics@0.0.1","gitHead":"1097d7a0c5bda04ba3b8ee8079a4d71b30f026b3","_nodeVersion":"18.20.3","_npmVersion":"10.7.0","dist":{"integrity":"sha512-TaQBQ4PCJ6NLihmDK9Tgvra/HfSnBV+krTv0ukk72u5lvqS6dwbsmU9Goi21R9B8vfICnCvj1gjf/rvsrLnkTQ==","shasum":"f2f0f5db65ce1cef64eecd02c4eaf661a621c26f","tarball":"https://registry.npmjs.org/@airsoko/next-analytics/-/next-analytics-0.0.1.tgz","fileCount":35,"unpackedSize":25273,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCItKmkwdN1QjANDbVTyjJIjahXWtdfyt41D303AKkPKQIhAN7AH/3EowzcAUaEiSNlp8toQ2Da8fLEQsuscEf5AJ14"}]},"_npmUser":{"name":"cluewax","email":"cluewaxing@gmail.com"},"directories":{},"maintainers":[{"name":"cluewax","email":"cluewaxing@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/next-analytics_0.0.1_1736706410957_0.004372853965598944"},"_hasShrinkwrap":false}},"time":{"created":"2025-01-12T18:26:50.868Z","0.0.1":"2025-01-12T18:26:51.140Z","modified":"2025-01-12T18:26:51.439Z"},"maintainers":[{"name":"cluewax","email":"cluewaxing@gmail.com"}],"description":"This npm package provides utility functions and TypeScript types for the Airsoko API.","author":{"name":"macive"},"license":"UNLICENSED","readme":"# Airsoko api package\n\n<br/>\n\n## 📑 Table of Contents\n\n<details>\n<summary>Table</summary>\n\n- [Overview](#overview)\n- [Installation ](#installation)\n  - [Prerequisites](#prerequisites)\n  - [Installation](#global-installation)\n  - [Using Airsoko ](#Project-Installation)\n  - [Updating](#updating)\n  - [Uninstallation](#uninstalling)\n- [API Reference](#api-reference)\n- [License](#license)\n- [Built With](#built-with)\n\n    </details>\n\n# @airsoko/next-analytics\n\n[![npm version](https://img.shields.io/npm/v/@airsoko/next-analytics.svg)](https://www.npmjs.com/package/@airsoko/next-analytics)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\nA lightweight and easy-to-use analytics package for Next.js applications. This package integrates Matomo analytics into your Next.js project, providing powerful tracking capabilities with minimal setup.\n\n---\n\n## Features\n\n- **Seamless Matomo Integration**: Easily integrate Matomo analytics into your Next.js app.\n- **Custom Event Tracking**: Track custom events with a simple API.\n- **URL Exclusions**: Exclude specific URLs from tracking using regex patterns.\n- **Route Change Tracking**: Automatically track route changes in Next.js.\n- **Secure Script Injection**: Supports Trusted Types for secure script loading.\n- **Environment Variable Support**: Configure Matomo settings via environment variables.\n\n---\n\n## Installation\n\nInstall the package using npm or yarn:\n\n```bash\nnpm install @airsoko/next-analytics\n```\n\nor\n\n```bash\nyarn add @airsoko/next-analytics\n```\n\n### Prerequisites\n\n- Node.js (version 16 or higher)\n- npm (or yarn)\n\n### Uninstalling\n\nIf you wish to uninstall Airsoko next, use:\n\n```sh\nnpm uninstall  @airsoko/next-analytics\n```\n\n# @airsoko/next-analytics\n\n![npm](https://img.shields.io/npm/v/@airsoko/next-analytics) ![license](https://img.shields.io/npm/l/@airsoko/next-analytics)\n\n## Quick Start\n\n### 1. Set Up Environment Variables\n\nAdd the following environment variables to your `.env` file:\n\n```env\nNEXT_PUBLIC_AIRSOKO_ANALYTICS_URL=https://analytics.example.com  # Matomo server URL\nNEXT_PUBLIC_AIRSOKO_ANALYTICS_SITE_ID=1                         # Matomo site ID\n```\n\n### 2. Use the Hook in Your Next.js App\n\nImport and use the `useAirsokoTracking` hook in your `_app.tsx` or any other component:\n\n```tsx\nimport { useEffect } from \"react\";\n\n// Constants\nconst AIRSOKO_ANALYTICS_URL = process.env.NEXT_PUBLIC_AIRSOKO_ANALYTICS_URL;\nconst AIRSOKO_ANALYTICS_SITE_ID = process.env.NEXT_PUBLIC_AIRSOKO_ANALYTICS_SITE_ID;\n\n/**\n * Custom hook to initialize Matomo tracking.\n */\nexport const useAirsokoTracking = () => {\n  useEffect(() => {\n    init({\n      url: AIRSOKO_ANALYTICS_URL,\n      siteId: AIRSOKO_ANALYTICS_SITE_ID,\n      excludeUrlsPatterns: [/^\\/login\\.php/, /\\?token=.+/], // Exclude login pages and token-based URLs\n    });\n  }, []);\n};\n```\n\n### 3. Initialize Tracking in Your App\n\nUse the `useAirsokoTracking` hook in your `_app.tsx` or main component:\n\n```tsx\nimport React from \"react\";\nimport { useAirsokoTracking } from \"@airsoko/next-analytics\";\n\nconst App = () => {\n  // Initialize Matomo tracking\n  useAirsokoTracking();\n\n  return (\n    <div>\n      <h1>Welcome to My App</h1>\n      <p>Matomo tracking is now active!</p>\n    </div>\n  );\n};\n\nexport default App;\n```\n\n## Configuration Options\n\nThe `init` function accepts the following options:\n\n| Option                  | Type                     | Default Value   | Description                                                   |\n| ----------------------- | ------------------------ | --------------- | ------------------------------------------------------------- |\n| `url`                   | `string`                 | Required        | The URL of your Matomo server.                                |\n| `siteId`                | `string`                 | Required        | The site ID for Matomo tracking.                              |\n| `jsTrackerFile`         | `string`                 | `\"matomo.js\"`   | The JavaScript tracker file for Matomo.                       |\n| `phpTrackerFile`        | `string`                 | `\"matomo.php\"`  | The PHP tracker file for Matomo.                              |\n| `excludeUrlsPatterns`   | `RegExp[]`               | `[]`            | Regex patterns to exclude specific URLs from tracking.        |\n| `disableCookies`        | `boolean`                | `false`         | Disable cookies for tracking.                                 |\n| `onRouteChangeStart`    | `(path: string) => void` | `undefined`     | Callback triggered when a route change starts.                |\n| `onRouteChangeComplete` | `(path: string) => void` | `undefined`     | Callback triggered when a route change completes.             |\n| `onInitialization`      | `() => void`             | `undefined`     | Callback triggered when Matomo is initialized.                |\n| `nonce`                 | `string`                 | `undefined`     | Nonce value for Content Security Policy (CSP) compliance.     |\n| `trustedPolicyName`     | `string`                 | `\"matomo-next\"` | Name of the Trusted Types policy for secure script injection. |\n\n## Advanced Usage\n\n### Custom Event Tracking\n\nYou can push custom events to Matomo using the `push` function:\n\n```tsx\nimport { push } from \"@airsoko/next-analytics\";\n\n// Track a custom event\npush([\"trackEvent\", \"Category\", \"Action\", \"Label\", 100]);\n```\n\n### Excluding URLs\n\nTo exclude specific URLs from tracking, use the `excludeUrlsPatterns` option:\n\n```tsx\ninit({\n  url: NEXT_PUBLIC_AIRSOKO_ANALYTICS_URL,\n  siteId: NEXT_PUBLIC_AIRSOKO_ANALYTICS_SITE_ID,\n  excludeUrlsPatterns: [/^\\/login/, /^\\/admin/], // Exclude login and admin pages\n});\n```\n\n## Troubleshooting\n\n### 1. Matomo Not Tracking\n\n- Ensure the `NEXT_PUBLIC_AIRSOKO_ANALYTICS_URL` and `NEXT_PUBLIC_AIRSOKO_ANALYTICS_SITE_ID` environment variables are correctly set.\n- Check the browser console for errors related to Matomo script loading.\n\n### 2. Trusted Types Errors\n\n- If you encounter Trusted Types errors, ensure your server supports the Trusted Types API or disable it by setting `trustedPolicyName` to `undefined`.\n\n## License\n\nThis project is licensed under the MIT License. See the LICENSE file for details.\n\n## Contributing\n\nContributions are welcome! Please open an issue or submit a pull request for any improvements or bug fixes.\n\n## Support\n\nFor support or questions, please open an issue on the GitHub repository.\n\n## Changelog\n\n### v0.0.1 (Initial Release)\n\n- Initial release of `@airsoko/next-analytics`.\n- Supports Matomo tracking, custom events, and URL exclusions.\n\n## 🤝 Contributing\n\nContributions to improve this package are welcome. Please adhere to the project's coding standards and commit guidelines.\n\n## License\n\nMIT License\n\n## ⚒️ Built With\n\n- ![@types/node](https://img.shields.io/badge/@types/node-40A2D8?style=for-the-badge&logo=%40types%2Fnode&logoColor=white)\n- ![typescript](https://img.shields.io/badge/typescript-40A2D8?style=for-the-badge&logo=typescript&logoColor=white)\n\n  ***\n\n  _🌟 This README was generated with 💖 by [Airsoko](https://github.com/airsoko)_\n","readmeFilename":"README.md"}