@airsoko/next-analytics NPM

Airsoko api package

📑 Table of Contents

Overview
Installation
API Reference
License
Built With

@airsoko/next-analytics

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

Features

Seamless Matomo Integration: Easily integrate Matomo analytics into your Next.js app.
Custom Event Tracking: Track custom events with a simple API.
URL Exclusions: Exclude specific URLs from tracking using regex patterns.
Route Change Tracking: Automatically track route changes in Next.js.
Secure Script Injection: Supports Trusted Types for secure script loading.
Environment Variable Support: Configure Matomo settings via environment variables.

Installation

Install the package using npm or yarn:

npm install @airsoko/next-analytics

yarn add @airsoko/next-analytics

Prerequisites

Node.js (version 16 or higher)
npm (or yarn)

Uninstalling

If you wish to uninstall Airsoko next, use:

npm uninstall  @airsoko/next-analytics

@airsoko/next-analytics

npm license

Quick Start

1. Set Up Environment Variables

Add the following environment variables to your .env file:

NEXT_PUBLIC_AIRSOKO_ANALYTICS_URL=https://analytics.example.com  # Matomo server URL
NEXT_PUBLIC_AIRSOKO_ANALYTICS_SITE_ID=1                         # Matomo site ID

2. Use the Hook in Your Next.js App

Import and use the useAirsokoTracking hook in your _app.tsx or any other component:

import { useEffect } from "react";

// Constants
const AIRSOKO_ANALYTICS_URL = process.env.NEXT_PUBLIC_AIRSOKO_ANALYTICS_URL;
const AIRSOKO_ANALYTICS_SITE_ID = process.env.NEXT_PUBLIC_AIRSOKO_ANALYTICS_SITE_ID;

/**
 * Custom hook to initialize Matomo tracking.
 */
export const useAirsokoTracking = () => {
  useEffect(() => {
    init({
      url: AIRSOKO_ANALYTICS_URL,
      siteId: AIRSOKO_ANALYTICS_SITE_ID,
      excludeUrlsPatterns: [/^\/login\.php/, /\?token=.+/], // Exclude login pages and token-based URLs
    });
  }, []);
};

3. Initialize Tracking in Your App

Use the useAirsokoTracking hook in your _app.tsx or main component:

import React from "react";
import { useAirsokoTracking } from "@airsoko/next-analytics";

const App = () => {
  // Initialize Matomo tracking
  useAirsokoTracking();

  return (
    <div>
      <h1>Welcome to My App</h1>
      <p>Matomo tracking is now active!</p>
    </div>
  );
};

export default App;

Configuration Options

The init function accepts the following options:

Option	Type	Default Value	Description
`url`	`string`	Required	The URL of your Matomo server.
`siteId`	`string`	Required	The site ID for Matomo tracking.
`jsTrackerFile`	`string`	`"matomo.js"`	The JavaScript tracker file for Matomo.
`phpTrackerFile`	`string`	`"matomo.php"`	The PHP tracker file for Matomo.
`excludeUrlsPatterns`	`RegExp[]`	`[]`	Regex patterns to exclude specific URLs from tracking.
`disableCookies`	`boolean`	`false`	Disable cookies for tracking.
`onRouteChangeStart`	`(path: string) => void`	`undefined`	Callback triggered when a route change starts.
`onRouteChangeComplete`	`(path: string) => void`	`undefined`	Callback triggered when a route change completes.
`onInitialization`	`() => void`	`undefined`	Callback triggered when Matomo is initialized.
`nonce`	`string`	`undefined`	Nonce value for Content Security Policy (CSP) compliance.
`trustedPolicyName`	`string`	`"matomo-next"`	Name of the Trusted Types policy for secure script injection.

Advanced Usage

Custom Event Tracking

You can push custom events to Matomo using the push function:

import { push } from "@airsoko/next-analytics";

// Track a custom event
push(["trackEvent", "Category", "Action", "Label", 100]);

Excluding URLs

To exclude specific URLs from tracking, use the excludeUrlsPatterns option:

init({
  url: NEXT_PUBLIC_AIRSOKO_ANALYTICS_URL,
  siteId: NEXT_PUBLIC_AIRSOKO_ANALYTICS_SITE_ID,
  excludeUrlsPatterns: [/^\/login/, /^\/admin/], // Exclude login and admin pages
});

Troubleshooting

1. Matomo Not Tracking

Ensure the NEXT_PUBLIC_AIRSOKO_ANALYTICS_URL and NEXT_PUBLIC_AIRSOKO_ANALYTICS_SITE_ID environment variables are correctly set.
Check the browser console for errors related to Matomo script loading.

2. Trusted Types Errors

If you encounter Trusted Types errors, ensure your server supports the Trusted Types API or disable it by setting trustedPolicyName to undefined.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contributing

Contributions are welcome! Please open an issue or submit a pull request for any improvements or bug fixes.

Support

For support or questions, please open an issue on the GitHub repository.

Changelog

v0.0.1 (Initial Release)

Initial release of @airsoko/next-analytics.
Supports Matomo tracking, custom events, and URL exclusions.

🤝 Contributing

Contributions to improve this package are welcome. Please adhere to the project's coding standards and commit guidelines.

License

MIT License

⚒️ Built With

🌟 This README was generated with 💖 by Airsoko

jsmin

0.0.1

1 year ago