Ahoy.js is a client-side JavaScript analytics library designed for simple and powerful visit and event tracking. It currently stands at version 0.4.5 and is actively maintained, though a specific release cadence isn't defined. The library's core function is to capture user interactions, such as unique visits, page views, clicks, submits, and custom events, sending this raw data via `POST` requests to a configurable backend endpoint. A key differentiator is its backend-agnostic design, allowing developers to integrate it with any server-side technology, including a dedicated Ruby gem for Rails applications. It automatically manages visit and visitor tokens (expiring after 4 hours and 2 years, respectively) and provides comprehensive data points like referrer, landing page, and event properties, which can be further enriched on the server with IP, user agent, and authentication details. The library also offers robust configuration options for URL endpoints, cookie management, cross-domain tracking, and debug logging.
npm install ahoy.jsVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to configure Ahoy.js for various tracking scenarios, including custom event tracking, page views, clicks, and form submissions, along with essential cross-domain and debugging settings.
For specific change tracking needs, use `ahoy.track()` with a custom event name and manually attach event listeners to relevant input fields.
Ensure you have a server-side implementation (e.g., a custom API endpoint or the Ahoy gem for Rails) configured to receive `POST` requests at `/ahoy/visits` and `/ahoy/events` (or custom configured URLs).
Configure Ahoy.js with `ahoy.configure({ cookieDomain: 'yourdomain.com' });` to ensure cookies are shared across all subdomains.Enable credential sending with `ahoy.configure({ withCredentials: true });`. Also, ensure your server-side CORS policy allows `Access-Control-Allow-Credentials: true` and appropriate `Origin` headers.Implement strict server-side validation for the `time` property of incoming events. A common recommendation is to only accept events where `(server_time - 1 minute) < client_time <= server_time`.
Verify that your backend server is running and accessible at the specified URL paths (`/ahoy/visits` and `/ahoy/events` by default). Check for firewall rules, DNS resolution, and correct `urlPrefix` configuration.
Ensure your server-side framework (e.g., Rails, Express.js, etc.) has routes configured to accept `POST` requests at the URLs specified in `ahoy.configure()` and that these routes lead to appropriate controllers or handlers.
On the server, confirm that the authenticated user's ID is being extracted from the request (e.g., from a session, JWT, or other authentication mechanism). If operating across different domains/subdomains, ensure `ahoy.configure({ withCredentials: true });` is set on the client, and your server is configured for CORS with credentials.No dependency data recorded yet.