Track

Learn how to track an event using a standalone function.

This function tracks an event on behalf of a user from any JavaScript environment, such as a server or a sandboxed script.

Unlike the track method of the SDK instance, which completes the event with the details of the current session, this function sends the event as given. You provide everything needed to attribute the event to the user: the client ID, the time it occurred, and the tab and page where it happened.

Signature

This function has the following signature:

function track<T extends EventType>(event: TrackedEvent<T>, options: TrackOptions): Promise<void>;

The result is a Promise that resolves once the event is sent, or rejects if the request fails.

Example

Here is a minimal example of how to use this function:

import {track} from '@croct/plug/api';
await track(  {    type: 'goalCompleted',    payload: {      goalId: 'signup',    },    clientId: '00000000-0000-0000-0000-000000000001',    timestamp: Date.now(),    context: {      tabId: '00000000-0000-0000-0000-000000000002',      url: 'https://example.com/signup',    },  },  {    appId: '00000000-0000-0000-0000-000000000000',  },);

Parameters

The following list describes the supported parameters:

event object

The event to track.

type string

The type of the event, such as goalCompleted or orderPlaced.

For a list of supported events, see the Event reference.

payload EventPayload

The properties of the event.

The function sends the payload as given, so it follows the Processed properties of the event type in the Event reference, rather than the input properties the SDK instance accepts. For example, a userSignedUp event takes a patch instead of a profile, and cart events take the lastUpdateTime of the cart.

User ID

Events that identify a user take a userId, which the function sends as the externalUserId processed property.

clientId string

The ID of the client (browser), in the form of a UUID.

This must be a persistent identifier that uniquely identifies the user across sessions.

timestamp number

The time the event occurred, in milliseconds since the Unix epoch.

context EventContext

The context in which the event occurred.

url string

The URL of the page the client was on when the event was tracked.

tabId(optional) string

The UUID that uniquely identifies the tab across the session.

timeZone(optional) string

The user’s time zone as an IANA time zone ID, such as America/New_York.

metadata(optional) object

Additional information that may be useful to include as part of the event metadata.

A common use case is to record the version of the application that generated the event for later analysis when exporting the events.

The following restrictions apply:

Up to 5 entries
Keys must be strings up to 20 characters long, starting with a letter or underscore and optionally followed by letters, digits, or underscores
Values must be strings up to 300 characters long

userToken(optional) string

A base64-encoded JSON Web Token (JWT) that identifies the user.

If the Require signed token option is enabled in the Application settings, a signed JWT is required. In this case, the token must be signed using an API key with Issue user tokens permission, or the request will fail with an authorization error.

clientIp(optional) string

The IP address of the client (end-user).

Passing 127.0.0.1 makes the API uses IP address of the incoming request, which is useful for local development.

If not specified or unknown, geographic location information will be limited or unavailable.

clientAgent(optional) string

The user agent of the client (browser).

If not specified or unknown, device technology information will be limited or unavailable.

options object

The tracking options.

appId(optional) string

The Application ID to use for client-side requests.

This option is required for client-side applications. For server-side applications, use the apiKey option instead. Specifying both will result in an error.

apiKey(optional) string

The API key to use for server-side requests.

This option is required for server-side applications. For client-side applications, use the appId option instead. Specifying both will result in an error.

Keep your API key safe

Never use your API key in client-side code, only in server-side environments.

timeout(optional) number

The maximum fetch time in milliseconds.

Once reached, the SDK will abort the request and reject the promise with a timeout error.

baseEndpointUrl(optional) string

The base URL to use for the API calls.

By default, the SDK uses the production endpoint. This option is helpful for testing purposes and allows you to point the SDK to another environment, such as a mock server.

These are the endpoints that use the base URL:

Path	Description
/client/web/track	Endpoint for client-side tracking.
/external/web/track	Endpoint for server-side tracking.

See Integration tests for more information on how to mock the API calls.

extra(optional) object

Additional options to pass to the fetch function.

logger(optional) object

A custom logger to handle log messages.

By default, all logs are suppressed.

debug (message: string)=>void: A function to log debug messages.
info (message: string)=>void: A function to log informational messages.
warn (message: string)=>void: A function to log warning messages.
error (message: string)=>void: A function to log error messages.