/ahoy.js

Simple, powerful JavaScript analytics

Primary LanguageJavaScriptMIT LicenseMIT

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 after jQuery.

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

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:

var ahoy = {
  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);

Reference

To track visits across multiple subdomains, add this before the javascript files.

var ahoy = {"domain": "yourdomain.com"};

TODO

  • Send events in batches
  • Add page and section for automatic events
  • Add trackContent method
  • Remove jQuery dependency
  • Customize endpoints

History

View the changelog

Contributing

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