Skip to main content

Track events

Platform:
Version:

With the justtrack SDK, you can monitor and record user behavior through events. These allow you to track how your users are using your app. For each event, you can also specify dimensions which you can later use to filter, sort, and group your events in the dashboard.

In this guide, you'll learn to:

  • Track predefined events
  • Track custom events
  • Track events with values
  • Check live events in the dashboard

Track predefined events​

With our SDK, you can track user behavior using predefined events. These events are defined by justtrack and are given special attention in the platform. For example, some metrics are calculated for you if you send data in certain predefined events.

info

You can find our list of predefined events here.

To track an event you need to pass your event to the publishEvent method of your JustTrackSdk instance:

await JustTrackSdk.publishEvent(new JtLoginEvent('success', 'email'));

Here, JtLoginEvent is a subclass of AppEvent. It represents a JtLoginEvent and accepts two predefined dimensions, called jt_action and jt_method. In this example, you pass the values for those dimensions in the constructor.

You can add more dimensions to an event by calling .addDimension():

await JustTrackSdk.publishEvent(new JtLoginEvent('success', 'email')
    .addDimension('dimension_name', 'value'));

This sends the event to the justtrack platform where you can visualize and analyze your data.

Track custom events​

Along with predefined events, you can also track custom events. You define these events yourself, and they're not given any special attention in the platform.

To track a custom event, pass an AppEvent object to the publishEvent method of your JustTrackSdk instance:

await JustTrackSdk.publishEvent(new AppEvent('my_event'));

When you create an AppEvent object, you can supply it with your own event name, like my_event.

You can add dimensions to your custom event with .addDimension():

await JustTrackSdk.publishEvent(new AppEvent('my_event')
    .addDimension('dimension_name', 'value'));

This sends the event to the justtrack platform where you can visualize and analyze your data.

Set global dimensions​

Some dimensions describe the user or the app rather than a single event, such as the app theme a user picked or the onboarding flow they went through. Instead of adding those to every event, set them once as a global dimension. The SDK stores the value and attaches it to every event you track afterwards.

You get three global dimensions, which arrive in the platform as the jt_global_0, jt_global_1, and jt_global_2 predefined dimensions:

await JustTrackSdk.setGlobalDimension0('dark_theme');
await JustTrackSdk.setGlobalDimension1('onboarding_v2');
await JustTrackSdk.setGlobalDimension2('returning_user');

Global dimensions persist across app launches, so you only need to set one again when its value changes.

To clear a global dimension, pass null:

await JustTrackSdk.setGlobalDimension0(null);
info

If you set jt_global_0, jt_global_1, or jt_global_2 directly on an event, that value wins for that event. The global value still applies to every other event.

Track events with values​

Events can carry numeric values along with dimensions. This is useful for tracking metrics like counts, durations, or monetary amounts.

Track counts​

Use count values to track quantities like level completions, items collected, or actions performed:

await JustTrackSdk.publishEvent(new AppEvent('level_complete')
    .setValue(new Value(15, Unit.Count))
    .addDimension('difficulty', 'hard'));

Track time​

Use time values to track durations like session length, time spent on a screen, or task completion time:

// Track time in seconds
await JustTrackSdk.publishEvent(new AppEvent('session_ended')
    .setValue(new Value(342.5, Unit.Seconds))
    .addDimension('screen', 'home'));

// Or in milliseconds
await JustTrackSdk.publishEvent(new AppEvent('animation_complete')
    .setValue(new Value(1500, Unit.Milliseconds)));

Track monetary values​

Use monetary values to track virtual currency transactions, in-app spending, or other financial metrics:

await JustTrackSdk.publishEvent(new AppEvent('virtual_currency_spent')
    .setValue(new Money(4.99, 'USD'))
    .addDimension('item', 'premium_pack'));

Event restrictions​

When you create events, you must adhere to the following requirements:

  • Event name
    • Can't be empty
    • Must be shorter than 256 characters
    • Is case-sensitive
    • Can only consist of printable ISO 8859-1 characters (U+0020 to U+007E as well as U+00A0 to U+00FF)
  • Dimension names
    • Must be shorter than 256 characters
    • May only consist of:
      • Lowercase letters in the Latin alphabet (U+0061 to U+007A)
      • Underscores (_) (U+005F)
      • Numbers (0-9) (U+0030 to U+0039)
  • Dimension values
    • Must be shorter than 4096 characters
    • Can only consist of printable ISO 8859-1 characters (U+0020 to U+007E as well as U+00A0 to U+00FF)
  • Other restrictions
    • Maximum of 10 dimensions per event
    • Event values must be finite (not NaN or Infinity)
    • Currency codes must be 3-letter uppercase ISO 4217 strings (e.g., "USD", "EUR")
danger

If your event doesn't match these criteria, it won't be recorded in the justtrack platform.

Check live events in the dashboard​

After you send your first event, you can check the Live Events section on your SDK integration page in the justtrack dashboard.

Jump to