Event tracking

Events track user interactions with your application, such as button clicks, content views, purchases, and more. They feed the personalization engine and help you measure how users interact with your application and track conversions.

The following sections provide examples of how you can use the JavaScript SDK to track these events in your application

Basic usage

To track an event, you need to call the track method of the SDK.

This method takes two parameters, the event name and the event properties, as shown in the following example:

import croct from '@croct/plug';

async function onCheckoutCompleted() {
  croct.track('goalCompleted', {
    goalId: 'paymentApproved',
  });
}

const button = document.getElementById('checkout-button');

button.addEventListener('click', onCheckoutCompleted);

For a list of all available events, see the Events reference.

Recommended events

Tracking events can unlock valuable features in the platform, like measuring conversion rates. Although optional, it's recommended to track certain events in your application for better results.

The following sections describe some recommended events and why they are important.

Goal completion

Perhaps the most important event to track is the completion of a goal. It's the event that allows you to measure conversion rates and other metrics.

To track goal completion, you need to call the track method with the goalCompleted event name whenever a user completes a goal that is relevant to your business.

For example, if you have a newsletter subscription form, you might want to track when a user subscribes to your newsletter:

croct.track('goalCompleted', {
  goalId: 'newsletter-subscription',
});

For more information, see the Goal completed event reference.

User signup

Tracking user signups allows you to link an identifier to a user profile, enabling you to recognize users across devices and sessions.

To track user signup, you need to call the track method with the userSignedUp event name, passing the user identifier and any other relevant information:

croct.track('userSignedUp', {
  userId: '123',
  profile: {
    firstName: 'John',
    lastName: 'Doe',
    email: 'john@example.com',
  }
});

For more information, see the User signed up event reference.

Order confirmation

If you have an e-commerce or subscription service, tracking orders allows you monitor revenue and other important metrics.

To track orders, you need to call the track method with the orderPlaced event name, passing the details of the order:

croct.track('orderPlaced', {
  order: {
    orderId: '6ZT6J',
    currency: 'USD',
    total: 776.49,
    items: [
      {
        index: 0,
        total: 699.00,
        quantity: 1,
        product: {
          productId: 'U42P8',
          name: 'Smartphone 9',
          displayPrice: 699.00
        }
      },
      {
        index: 1,
        total: 77.49,
        quantity: 1,
        product: {
          productId: 'A2B4C',
          name: 'Smartphone 9 case',
          displayPrice: 77.49
        }
      }
    ]
  }
});

For more information, see the Order placed event reference.

Cart interactions

If you have an e-commerce application, tracking shopping cart interactions allows you to create user segments based on their cart contents and checkout stage. For more information on how to use this information, see the Shopping variables reference.

There are three events that you can track to monitor shopping cart interactions: cartViewed, cartModified, and checkoutStarted. They all take a cart property that describes the contents of the shopping cart.

Cart viewed

This event tracks the contents of the shopping cart whenever a user views it.

Here is an example of how to track this event:

croct.track('cartViewed', {
  cart: {
    currency: 'USD',
    total: 699.00,
    items: [
      {
        index: 0,
        total: 699.00,
        quantity: 1,
        product: {
          productId: 'U42P8',
          name: 'Smartphone 9',
          displayPrice: 699.00
        }
      }
    ]
  }
});

For more information, see the Cart viewed event reference.

Cart modified

The cartModified event tracks changes made to the shopping cart, such as adding items, applying coupons, or changing quantities.

Building upon the previous example, if the user adds a phone case to the shopping cart that already includes a smartphone, you can track the following event:

croct.track('cartModified', {
  cart: {
    currency: 'USD',
    total: 776.49,
    items: [
      {
        index: 0,
        total: 699.00,
        quantity: 1,
        product: {
          productId: 'U42P8',
          name: 'Smartphone 9',
          displayPrice: 699.00
        }
      },
      {
        index: 1,
        total: 77.49,
        quantity: 1,
        product: {
          productId: 'A2B4C',
          name: 'Smartphone 9 case',
          displayPrice: 77.49
        }
      }
    ]
  }
});

Note that you do not need to track the exact changes made to the shopping cart, such as adding or removing items, changing quantities, etc. All you need to do is provide the current state and we will automatically update the context accordingly.

For more information, see the Cart modified event reference.

Checkout started

The checkoutStarted event tracks when a user starts the checkout process, usually by clicking on the button that takes them to the checkout page.

Here is an example of how to track this event:

croct.track('checkoutStarted', {
  cart: {
    currency: 'USD',
    total: 776.49,
    items: [
      {
         index: 0,
         total: 699.00,
         quantity: 1,
         product: {
           productId: 'U42P8',
           name: 'Smartphone 9',
           displayPrice: 699.00
         }
      },
      {
         index: 1,
         total: 77.49,
         quantity: 1,
         product: {
           productId: 'A2B4C',
           name: 'Smartphone 9 case',
           displayPrice: 77.49
         }
      }
    ]
  }
});

For more information, see the Checkout started event reference.