Ahoy.js

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

Installation

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';

How It Works

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

Events

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

All Events

Track all views and clicks with:

ahoy.trackAll();

Set the page with:

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

And sections with:

<div data-section="Header">
  <a href="/home">Home</a>
</div>

These are included in event properties if set.

Views

ahoy.trackView();

Name - $view

Properties

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

Clicks

ahoy.trackClicks();

Name - $click

Properties

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

Submits

ahoy.trackSubmits();

Name - $submit

Changes

ahoy.trackChanges();

Name - $change

Development

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);

Configuration

Here’s the default configuration:

ahoy.configure({
  urlPrefix: "",
  visitsUrl: "/ahoy/visits",
  eventsUrl: "/ahoy/events",
  cookieDomain: null,
  page: null,
  platform: "Web",
  useBeacon: false,
  startOnReady: true,
  trackVisits: true
});

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.

Subdomains

To track visits across multiple subdomains, use:

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

Dev Setup

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

And visit http://localhost:8080/__zuul in your browser.

TODO

• Send events in batches
• Add page and section for automatic events
• Add trackContent method

History

View the changelog

Contributing

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