Track product usage

The tracking script sends events from your product, such as a login or a created invoice, to CustomerCatalyst. Each night they are added up per customer and feed the customer’s product usage score. See How scores work.

You need someone who can edit your product’s web pages. The full reference is in Tracking SDK.

Before you start

• A public key with the Usage tracking ability, with your product’s site on its list of allowed sites. Events from any other site are refused. See API keys.
• Product usage metrics. Under Settings › Company metrics › Product usage, add a metric for each thing you want to count, with the source Tracked. Each metric has a Slug, such as invoice_created. That slug is the event name your product sends.
• Your customers’ CustomerCatalyst IDs. Your product has to know which CustomerCatalyst customer the signed-in user belongs to.

Set it up

1. Add the script to the <head> of your product’s pages, with your key:

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

   The attribute is api-key, not data-api-key.

2. Once you know who is signed in, tell the script which customer they belong to:

   customercatalyst.identify({ customerId: '1755330002129x611465252565155800' });

3. Send an event whenever something you measure happens. Use the metric’s slug as the event name:

   customercatalyst.track('login');
   customercatalyst.track('invoice_created', 1500);

   The second argument is the amount to count. Without it, the event counts as 1.

Use the right customer ID

customerId must be the customer’s ID in CustomerCatalyst, not your own account ID, an email or a CRM ID. Events sent under any other ID are stored, but no customer is scored from them.

To get the IDs, export your customers under Settings › Data export.

How events become a score

For each Tracked metric, CustomerCatalyst adds up the amounts of the events whose name equals the metric’s slug, for each customer, over the metric’s period. It then places that total between the metric’s minimum and maximum. This happens every night, so new events show in scores the next day.

One track() call is one event. If you already know a quantity, send it once:

customercatalyst.track('invoices_created', 50); // one event that counts 50

Check that it works

Add debug to the script tag and open your browser’s console:

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

The console shows each event being queued and sent, and what the server accepted.

Nothing arrives?

• The site isn’t on the key’s list. The key is refused and the script stops sending. Add the site under API keys; it also appears there under Seen on sites not on the list.
• The key is wrong, revoked or lacks Usage tracking. The script stops sending on that key. Fix the key and reload the page.
• The event name doesn’t match a slug exactly. The event is stored but counts toward no metric.
• identify() wasn’t called first. track() throws an error until it is.

Privacy

Don’t put personal information such as names or email addresses in event names or metadata.