Tracking SDK

customercatalyst.js sends product usage events from the browser to CustomerCatalyst. It has no dependencies and no build step. For the setup walkthrough, see Track product usage.

Install

Script tag

<script src="https://cdn.customercatalyst.io/customercatalyst.js" api-key="pk_…"></script>

Attribute	Value
api-key	Your public key (pk_…) with the Usage tracking ability. Not data-api-key.
debug	Optional, no value. Turns on console logging (same as CustomerCatalyst.debug = true).

The tag creates a ready instance at window.customercatalyst. Loading the script twice reuses the first instance. If something else already sits at window.customercatalyst, it is replaced and a console warning says so.

Manual initialization

Leave out api-key and construct the instance yourself when you need more than one key on a page, the key is only known at runtime, or you bundle the file into your own build:

<script src="https://cdn.customercatalyst.io/customercatalyst.js"></script>
<script>
  var cc = new CustomerCatalyst('pk_…');
  cc.identify({ customerId: 'CUSTOMER_ID' });
  cc.track('login');
</script>

Don’t name your variable CustomerCatalyst or customercatalyst; those names belong to the class and the auto-created instance.

Keys and sites

The key only works on the sites listed on it, matched against the browser’s Origin. See API keys. A page on an unlisted site gets 403 and the SDK stops sending on that key.

API

Member	Does
new CustomerCatalyst(apiKey)	Creates an instance. Throws if apiKey isn’t a non-empty string.
identify({ customerId, customerName? })	Sets the customer for the following events. Required before track(). customerId is the customer’s CustomerCatalyst ID, up to 255 characters. Throws if missing or too long.
track(eventType, value?, metadata?)	Queues one event. eventType is the metric slug, up to 255 characters. value defaults to 1; it must be a finite number, 0 or more, and is rounded to 6 decimals. metadata must be a plain JSON-serialisable object, otherwise it is dropped with a warning and the event is still sent. Throws if identify() wasn’t called or eventType is blank or too long.
flush()	Returns a promise. Sends everything queued for this key now and resolves when the queue is empty, or after 5 seconds at most.
restart()	Resumes a key that a fatal error stopped. Only useful if the cause was temporary; for a wrong key, create a new instance.
stats	{ queued, droppedEvents, droppedBatches } for this key.
isStopped	true once a fatal error stopped this key. track() is then ignored.
CustomerCatalyst.debug	Page-wide switch for console logging. Keys are logged as their last 4 characters only.
CustomerCatalyst.init()	What the script tag runs to create window.customercatalyst. You don’t need to call it.

customercatalyst.identify({ customerId: 'CUSTOMER_ID', customerName: 'Acme' });
customercatalyst.track('report_generated', 1, { type: 'monthly' });

logoutButton.addEventListener('click', function (e) {
  e.preventDefault();
  customercatalyst.track('logout');
  customercatalyst.flush().then(function () { location.href = '/logout'; });
});

Batching and delivery

• Events are batched: up to 50 events or about 28 KB per request, and at most 10 requests per second for the whole page.
• A burst of track() calls in the same moment waits 50 ms and goes out as one request.
• Each event gets a unique ID, so an event sent twice is stored once.
• When the page is hidden or closed, anything still queued is sent with navigator.sendBeacon.
• Several keys on one page queue separately: one key waiting or failing doesn’t hold up another.

Limits

Limit	Value	When exceeded
Events per organization	50,000 per hour	Refused until the next hour. The SDK waits and retries.
customerId, eventType	255 characters each	identify() / track() throws.
value	0 or more, up to 12 digits and 6 decimals	Stored as 1.
Single event, with metadata	about 28 KB	Dropped with a warning.
Queue	1,000 events per page, 500 per key	New events are dropped with a warning until it drains.

Length is counted in characters (Unicode code points), so an emoji counts as one.

Errors

Response	SDK does
401, 403, 404	Stops the key. Discards its queue and ignores further track() calls. 401: key wrong, revoked or without Usage tracking. 403: site not on the key’s list.
400, 413, 422	Drops that batch, keeps sending the rest. Counted in stats.
408, 429, 5xx, network errors	Retries with increasing waits, up to 30 seconds apart. On 429 it waits as long as the server asks, at most 5 minutes. A batch is dropped after 10 failed attempts.

Content Security Policy

If your product sends a Content-Security-Policy, allow the script and its endpoint. See Content Security Policy.

Browser support

Current versions of Chrome, Firefox, Safari, Edge and Opera. Internet Explorer is not supported.