@threekit/analytics

@Threekit/Analytics

A package for recording analytics from a front-end application.

Features

• Record user interactions and events
• Track user selections and stage transitions
• Capture cart additions and purchase/quote events
• Log custom events for enhanced tracking

Installation

Install the package via your favorite package manager:

npm install @threekit/analytics

Initialization

It’s recommended to initialize the Session object as a global singleton in your front-end application:

const orgId = '...'; // the UUID for your org
const publicToken = '...'; // a public token for your org
const host = 'admin-fts.threekit.com'; // the host for your org

export const getCurrentSession = () => {
  const session = getSession({
    auth: { orgId, publicToken, host }
  });
  session.log = false;
  return session;
};

Recording Events

Options Show

When presenting a set of options to the user, such as a dropdown or grid, use this event to record the details of those options:

getCurrentSession().optionsShow({
  optionsSetId: attributeName,
  options: values.map((value) => ({
    optionId: value,
    optionName: value
  })),
  optionsType: OptionsType.Value
});

Option Interaction (Select)

Record the event when the user selects an option that was shown to them:

getCurrentSession().optionInteraction({
  optionsSetId: attributeName,
  interactionType: OptionInteractionType.Select,
  optionId: value
});

Stage Transition

In a multi-step configuration, each step is referred to as a stage. Use this event to record the start of each stage:

getCurrentSession().stage({ stageName: 'Confirm Selections' });

Add To Cart

For each item a user adds to the cart, record it with this event:

getCurrentSession().addToCart({
  assetId: itemId,
  configuration: simplifiedConfiguration as Configuration,
  itemCustomId: itemConfiguration['SKU'] as string | undefined,
  itemName: itemConfiguration['Description'] as string | undefined,
  itemPrice: itemConfiguration['Price'] as number | undefined,
  itemCount: itemConfiguration['skuQty'] as number | undefined
});

Quote (or Purchase)

When the user makes an order (or a purchase), record the event as follows:

const orderPrice = orderData.reduce(
  (previous, current) => previous + current.unitPrice * current.quantity,
  0
);

const cartItems = orderData.map((item) => {
  return {
    itemName: item.description,
    itemCustomId: item.name,
    itemPrice: item.unitPrice,
    itemCount: item.quantity
  };
});

getCurrentSession().quote({
  orderPrice,
  cart: cartItems
});

Share

When the user generates a URL to share the configuration with another user, record the event using:

getCurrentSession().share({
  shareLink: configurationUrl,
  shareType: ShareType.Share
});

Custom Events

For events in the user experience that don’t fit any predefined category, use a custom event:

getCurrentSession().custom({ customName: 'View Product List' });

Support

For support and questions, please reach out to [e-mail].