Ahoy.js

Common errors

• POST https://yourdomain.com/ahoy/visits net::ERR_CONNECTION_REFUSED

  cause The configured `visitsUrl` or `eventsUrl` does not point to an accessible or running backend service, or a network issue is preventing connection.
  fix 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.

• Failed to load resource: the server responded with a status of 404 (Not Found)

  cause Your backend application does not have the necessary routes defined to handle `POST` requests to the `/ahoy/visits` or `/ahoy/events` endpoints.
  fix 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.

• Analytics data is recorded, but user-specific information (like `user_id`) is missing in the backend.

  cause The server-side application is not correctly capturing the authenticated user from the request, or `withCredentials` is not enabled for cross-origin requests, preventing session cookies from being sent.
  fix 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.

Warnings

• deprecated The `ahoy.trackChanges()` method is deprecated and should no longer be used for tracking input field changes.
  Fix: For specific change tracking needs, use `ahoy.track()` with a custom event name and manually attach event listeners to relevant input fields.
• gotcha Ahoy.js is a client-side library and requires a backend server to receive, process, and store analytics data. It is not a standalone analytics solution.
  Fix: 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).
• gotcha When tracking user activity across multiple subdomains (e.g., `www.example.com` and `blog.example.com`), the `cookieDomain` configuration must be explicitly set to the top-level domain.
  Fix: Configure Ahoy.js with `ahoy.configure({ cookieDomain: 'yourdomain.com' });` to ensure cookies are shared across all subdomains.
• gotcha If your Ahoy.js client is hosted on a different domain or subdomain than your analytics backend, and you rely on cookies for user authentication, `withCredentials` must be set to `true`.
  Fix: 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.
• gotcha Ahoy.js sends event `time` from the client. The server *must* validate this timestamp to prevent clients from sending manipulated or fraudulent historical/future events.
  Fix: 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`.

Install

• npm install ahoy.js npm
• yarn add ahoy.js yarn
• pnpm add ahoy.js pnpm

Imports

• ahoy
  wrong:

  const ahoy = require('ahoy.js');

  correct:

  import ahoy from 'ahoy.js';

  Ahoy.js primarily uses ES Modules for package imports. Direct `require()` is typically incorrect for modern bundlers and Node.js environments unless a specific CJS build is targeted.
• ahoy

  <script src="path/to/ahoy.js"></script>
  <script>
    ahoy.track('Page Load');
  </script>

  When included directly via a `<script>` tag in an HTML document, the `ahoy` object becomes globally available in the browser window.

Quickstart

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.

ahoy.configure({
  cookieDomain: "example.com", // Use for tracking across subdomains (e.g., app.example.com, blog.example.com)
  withCredentials: true,       // Essential for sending cookies across different domains/subdomains for authentication
  visitsUrl: "/api/analytics/visits", // Customize endpoint for visit tracking
  eventsUrl: "/api/analytics/events"  // Customize endpoint for event tracking
});

// Enable debug logging in the browser console
ahoy.debug();

// Track a custom event with properties
ahoy.track("Product Viewed", {
  productId: "SKU123",
  category: "Electronics",
  price: 499.99
});

// Track a page view, automatically capturing URL and title
ahoy.trackView();

// Track clicks on specific CSS selectors
ahoy.trackClicks(".add-to-cart-button, #checkout-link");

// Track form submissions on specific CSS selectors
ahoy.trackSubmits("#newsletter-signup-form");

// To force a new visit for testing (requires page reload)
// ahoy.reset();
// window.location.reload();