JavaScript SDK

The Accoil JavaScript SDK is a lightweight, dependency-free library for tracking users, accounts, and events directly from the browser. It loads asynchronously and uses a queue-based architecture, so you can call methods immediately without waiting for the script to finish loading.

Installation

Add the following snippet to your site's <head> or top-level template. It initializes the Accoil global object with a command queue and loads the tracker script asynchronously.

<script type="text/javascript">
(function() {
  var accoil = window.accoil = window.accoil || {q: []};
  var calls = ['load', 'identify', 'group', 'track'];
  for (var i = 0; i < calls.length; i++) (function(call) {
    accoil[call] = function() { accoil.q.push([call, arguments]); };
  })(calls[i]);
  var s = document.createElement('script');
  s.src = 'https://cdn.accoil.com/tracker.js';
  s.async = true;
  var f = document.getElementsByTagName('script')[0];
  f.parentNode.insertBefore(s, f);
})();
</script>

No package manager or build step is required. The snippet creates stub methods that buffer all calls into a queue (accoil.q). Once tracker.js finishes loading, the queue is flushed and all buffered calls are executed in order.

Initialization

After including the snippet, initialize the SDK with your API key:

accoil.load("YOUR_API_KEY");

Finding Your API Key

Your API key is available in the Accoil dashboard under Account > General Settings. Each product has its own key.

Place the load() call in the same template where you added the installation snippet. The SDK is ready to accept calls immediately -- they will be queued and executed once the script loads.

identify(userId, traits)

The identify call tells Accoil who the current user is. This is required before any track calls will be associated with the user. You should call identify on every page load for authenticated users.

accoil.identify("user_12345", {
  email: "alex@example.com",
  name: "Alex Keener",
  createdAt: "2024-08-01T12:00:00Z",
  role: "admin",
  plan: "enterprise"
});

Parameters

Parameter	Type	Required	Description
`userId`	string	Yes	A unique, stable identifier for the user.
`traits`	object	No	Key-value pairs of user attributes.

Recommended Traits

Trait	Type	Purpose
`email`	string	Primary user identity in the Accoil UI
`name`	string	Display name
`createdAt`	string (ISO 8601)	Enables tenure tracking
`role`	string	Filtering and segmentation

When to Call identify

Every page load for logged-in users. The SDK tracks the current user in memory and scopes all subsequent track calls to that user.
On sign-up or login, with the full set of known traits.
Whenever user traits change (e.g., role update, plan change).

group(groupId, traits)

The group call associates the current user with an account (organization) and records account-level traits. This is essential for B2B analytics, enabling account-level engagement scoring and segmentation.

accoil.group("account_67890", {
  name: "Acme Corp",
  status: "paid",
  plan: "enterprise",
  mrr: 100000,
  createdAt: "2023-01-15T12:00:00Z"
});

Parameters

Parameter	Type	Required	Description
`groupId`	string	Yes	A unique identifier for the account.
`traits`	object	No	Key-value pairs of account attributes.

Recommended Traits

Trait	Type	Purpose
`name`	string	Account name displayed in Accoil
`status`	string	Account state (`free`, `trial`, `paid`)
`plan`	string	Subscription tier
`mrr`	integer	Monthly recurring revenue in cents
`createdAt`	string (ISO 8601)	Account tenure tracking

When to Call group

When a user first signs up and is associated with an account.
When account attributes change (conversion, upgrade, downgrade, cancellation).
On each page load if you want to ensure the user-account association stays current.

track(eventName)

The track call records a user event. Accoil accepts only the event name -- no event properties. The event is automatically scoped to the most recently identified user.

accoil.track("Report_Created");

Parameters

Parameter	Type	Required	Description
`eventName`	string	Yes	The name of the event. Use clear, descriptive names (e.g., `Dashboard_Viewed`, `Report_Created`).

No Event Properties

The track call accepts only an event name. Do not pass a properties object -- it will be ignored. Send user and account attributes via identify and group calls instead.

When to Call track

Whenever a user performs a meaningful action in your product.
After the user has been identified with identify. If no user has been identified, track calls cannot be attributed.

Complete Working Example

Below is a full example showing the installation snippet, initialization, and all three call types used together in a page template:

<!DOCTYPE html>
<html>
<head>
  <!-- Accoil SDK Installation -->
  <script type="text/javascript">
  (function() {
    var accoil = window.accoil = window.accoil || {q: []};
    var calls = ['load', 'identify', 'group', 'track'];
    for (var i = 0; i < calls.length; i++) (function(call) {
      accoil[call] = function() { accoil.q.push([call, arguments]); };
    })(calls[i]);
    var s = document.createElement('script');
    s.src = 'https://cdn.accoil.com/tracker.js';
    s.async = true;
    var f = document.getElementsByTagName('script')[0];
    f.parentNode.insertBefore(s, f);
  })();
  </script>

  <!-- Initialize and identify on every page load -->
  <script type="text/javascript">
    // Initialize with your API key
    accoil.load("YOUR_API_KEY");

    // Identify the current user (call on every page load)
    accoil.identify("user_12345", {
      email: "alex@example.com",
      name: "Alex Keener",
      createdAt: "2024-08-01T12:00:00Z",
      role: "admin"
    });

    // Associate the user with their account
    accoil.group("account_67890", {
      name: "Acme Corp",
      status: "paid",
      plan: "enterprise",
      mrr: 100000
    });
  </script>
</head>
<body>
  <button onclick="accoil.track('Report_Created')">
    Create Report
  </button>
</body>
</html>

In a single-page application, call identify and group after authentication completes, then call track in response to user actions throughout the session.

Debugging Tips

Events not appearing in Accoil:

Verify your API key is correct in the accoil.load() call.
Confirm that identify is called before track. Track calls without a prior identify cannot be attributed to a user.
Check that the snippet is loading by inspecting the Network tab in your browser's developer tools. Look for a request to https://cdn.accoil.com/tracker.js.

Queue behavior:

All calls made before tracker.js finishes loading are buffered in window.accoil.q. You can inspect this array in the browser console to verify calls are being queued.

Verifying calls in the console:

After the SDK loads, you can inspect window.accoil in the browser console to confirm the library is initialized.
Check the Network tab for outbound requests to https://in.accoil.com to confirm data is being sent.

Common mistakes:

Calling track without a preceding identify call on the page.
Using a different API key than the one for your target product.
Placing the snippet after other scripts that depend on window.accoil being available.

JavaScript SDK

On this page