Products
Solutions
Resources

Flywheel.js client

This page will help you set up the Flywheel.js client so you can emit your own events to Flywheel with Javascript code.

NOTE: the Flywheel.js client currently only works in the browser. If you would like to emit events from a server, please Contact Us.

If you would rather use an HTML script snippet, please see the instructions in the main Flywheel.js docs.


Install the client

Install the flywheel.js client with your package manager:

npm install @flywheelapp/flywheel.js

We highly recommend not specifying a version so you get our latest client (that is the default with the above command). If you use an older client, you may not have access to newer functionality.

Initialize the client

import { FlywheelAnalytics } from "@flywheelapp/flywheel.js";

export const flywheel = FlywheelAnalytics.load({
  // NOTE: we highly recommend using an environment variable for your write key
  // instead of hard coding it in your source control
  writeKey: "PUT YOUR WRITE KEY HERE",
  apiHost: "theflywheel.app",
});

Your writeKey can be found

Usage

Below, you will find information on when and how to fire each event type. We follow the Segment Spec, parts of it are described briefly below in each section.


Identify Events

Identify events help connect events to data from other sources by providing a user's identifying information.

Critical identifying information that you should pass in the event (if available):

  • userId: the id of the user in your system

  • email

Other very helpful information that you can pass (if available): name, firstName, lastName, phone, title.

You can read more about them in the Segment Spec: Identify.

You will want to call identify events on sign in, sign up, and page load (if a user is already signed in).

// import `flywheel` or get from hook
signUpUser(req).then((user) => {
  flywheel.identify(user.id, {
    userId: user.id,
    name: user.name,
    email: user.email,
  });
});

signInUser(req).then((user) => {
  flywheel.identify(user.id, {
    userId: user.id,
    name: user.name,
    email: user.email,
  });
});

getCurrentUser().then((user) => {
  if (!user) return;
  flywheel.identify(user.id, {
    userId: user.id,
    name: user.name,
    email: user.email,
    // pass any other fields from above
  });
});


Pageview Events

Pageview events allow you to know the pages that a user visits. You can read more about them in the Segment Spec: Pageview.

If you app does not change the URL: you can add the following below the flywheel initialization:

(function () {
  flywheel.page(window.name, {
    title: document.title,
    url: document.URL,
    path: document.location.pathname,
  });
})();

If your app changes the URL: complete the following based on your setup.

If you use react-router, you can use the following hook:

import { useEffect } from "react";
import { useLocation } from "react-router-dom";
import { flywheel } from "./flywheel";

export const useFlywheelLocationChange = () => {
  const { pathname } = useLocation();

  useEffect(() => {
    flywheel.page(window.name, {
      title: document.title,
      url: document.URL,
      path: document.location.pathname,
    });
  }, [pathname]);
};

// Then call the hook in a top-level component that is always rendered, for example App:

export const App = () => {
  // ...
  useFlywheelLocationChange();
  // ...
}

If you do not use react-router, you can instead add the following below the flywheel initialization:

(function () {
  if (!Proxy) return;
  window.history.pushState = new Proxy(window.history.pushState, {
    apply: (target, thisArg, argArray) => {
      target.apply(thisArg, argArray);
      window.dispatchEvent(new Event("pushstate"));
      window.dispatchEvent(new Event("locationchange"));
    },
  });
  window.history.replaceState = new Proxy(window.history.replaceState, {
    apply: (target, thisArg, argArray) => {
      target.apply(thisArg, argArray);
      window.dispatchEvent(new Event("replacestate"));
      window.dispatchEvent(new Event("locationchange"));
    },
  });

  window.addEventListener("popstate", function () {
    window.dispatchEvent(new Event("locationchange"));
  });

  window.addEventListener("locationchange", function () {
    flywheel.page(window.name, {
      title: document.title,
      url: document.URL,
      path: document.location.pathname,
    });
  });
})();


Tracked Events

Tracked events allow you to know what a user did while on a given page. If you use the auto-track feature of flywheel.js, a lot of this will be handled for you. You can also send your own custom tracked events in addition to auto-track if you'd like.

We recommend you follow Segment's naming convention for clean data. You can also read more about them in the Segment Spec: Track.

Below is an example of how you can send a custom tracked event when a button is clicked.

import { flywheel } from "./flywheel";

export const Component = ({ user }: { user?: CurrentUser }) => {
  const onClick = () => {
    const properties = {
      email: user?.email,
      userId: user?.id,
    };

    flywheel.track("Special Button Clicked", properties);
  };

  return <button onClick={onClick}>Special Button</button>;
};