🔥 Visit and event tracking for JavaScript

• Easily track unique visitors
• Track events across page navigation

Use it with any backend. For Rails, check out the Ahoy gem.

Download ahoy.js and include it on your page.

<script src="ahoy.js"></script>

Or use Yarn:

yarn add ahoy.js

And import it with:

import ahoy from 'ahoy.js';

When someone lands on your website, they are assigned a visit token and a visitor token.

The visit token expires after 4 hours, in which a new visit is created. Visits are useful for tracking metrics like monthly active users. The visitor token expires after 2 years. A POST request is sent to /ahoy/visits with:

• visit_token
• visitor_token
• referrer
• landing_page

The server can capture:

• ip
• user_agent
• user - from app authentication

And calculate things like:

• referring_domain and search_keyword from referrer
• utm_source, utm_medium, utm_term, utm_content, and utm_campaign from landing_page
• city, region, and country from ip
• browser, os, and device_type from user_agent

Track events with:

ahoy.track(name, properties);

A POST request is sent to /ahoy/events with:

• name
• properties
• time

The server can capture:

• visit_token - from cookies
• user - from app authentication

As a precaution, the server should reject times that do not match:

1 minute ago < time <= now

ahoy.trackView();

Name - $view

Properties

• url - https://www.streamflip.com
• title - Streamflip
• page - /

The page defaults to the path. Set the page with:

ahoy.configure({page: "Landing page"});

ahoy.trackClicks("#link1, #link2");

Name - $click

Properties

• tag - a
• id - account-link
• class - btn btn-primary
• page - /
• text - View Account
• href - /account

ahoy.trackSubmits("#form1, #form2");

Name - $submit

Properties

• tag - form
• id - form1
• class - form-inline
• page - /

Deprecated

ahoy.trackChanges("#input1, #input2");

Name - $change

Properties

• tag - input
• id - input1
• class - form-control
• page - /

Ahoy is built with developers in mind. You can run the following code in your browser’s console.

Force a new visit

ahoy.reset(); // then reload the page

Log messages

ahoy.debug();

Turn off logging

ahoy.debug(false);

Here’s the default configuration:

ahoy.configure({
  urlPrefix: "",
  visitsUrl: "/ahoy/visits",
  eventsUrl: "/ahoy/events",
  page: null,
  platform: "Web",
  useBeacon: true,
  startOnReady: true,
  trackVisits: true,
  cookies: true,
  cookieDomain: null,
  headers: {},
  visitParams: {},
  withCredentials: false,
  visitDuration: 4 * 60, // 4 hours
  visitorDuration: 2 * 365 * 24 * 60 // 2 years
});

When trackVisits is set to false, Ahoy.js will not attempt to create a visit on the server, but assumes that the server itself will return visit and visitor cookies.

To track visits across multiple subdomains, use:

ahoy.configure({cookieDomain: "yourdomain.com"});

Ahoy automatically associates users with visits and events if the user is authenticated on the server.

If you use cookies for authentication and the JavaScript library is on the same subdomain as the server, no additional configuration is needed.

If you use cookies and the JavaScript library is on a different domain or subdomain as the server, set:

ahoy.configure({withCredentials: true});

This will send credentials such as cookies, authorization headers or TLS client certificates to the server.

If you use headers for authentication, pass them with:

ahoy.configure({headers: {"Authorization": "Bearer ..."}});

If you use the Fetch API to make requests and the JavaScript library is on a different domain or subdomain as the server, Ahoy cookies are not sent to the server by default. You can pass the info in headers with:

fetch(url, {
  headers: {"Ahoy-Visit": ahoy.getVisitId(), "Ahoy-Visitor": ahoy.getVisitorId()}
});

The trackClicks, trackSubmits, and trackChanges functions now require selectors. The previous defaults were:

ahoy.trackClicks("a, button, input[type=submit]");
ahoy.trackSubmits("form");
ahoy.trackChanges("input, textarea, select");

The trackAll function has been removed. The equivalent code is:

ahoy.trackView();
ahoy.trackClicks("a, button, input[type=submit]");
ahoy.trackSubmits("form");
ahoy.trackChanges("input, textarea, select");

View the changelog

Everyone is encouraged to help improve this project. Here are a few ways you can help:

• Report bugs
• Fix bugs and submit pull requests
• Write, clarify, or fix documentation
• Suggest or add new features

To get started with development:

git clone https://github.com/ankane/ahoy.js.git
cd ahoy.js
yarn install
yarn build