@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 (do not use a private token in front-end app)
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;
};

The session object will automatically track users, sessions as well as various timing events.

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({
  assetId: assetId, // optional
  optionsSetId: optionSetName, // a unique string, can be anything but it will be the "name" of the option set in the UI
  options: values.map((value) => ({
    optionId: value, // any unique string is acceptable here.
    optionName: value // optional, but recommended, display name if you have one.
  })),
  optionsType: OptionsType.Value
});

If you know the assetId of the current objects, specifying it as assetId.

If the attribute is reference assets, be sure to use the individual option assetId as the optionId and specify the optionType as OptionsType.Asset.

getCurrentSession().optionsShow({
  assetId: assetId,
  optionsSetId: attributeName,
  options: values.map((value) => ({
    optionId: attributeOptionAssetId, // this should now be an assetId
    optionName: attributeOptionAssetName // optional, but recommended, the name of the assetId
  })),
  optionsType: OptionsType.Asset
});

Option Interaction (Select)

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

getCurrentSession().optionInteraction({
  optionsSetId: attributeName, // the same optionsSetId used in the ```optionsShow``` event
  interactionType: OptionInteractionType.Select,
  optionId: value // either the assetID or the string optionId specified for this option in the ```optionsShow``` event.
});

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' });

Queries

If the user makes a query you can record it using this event, you can record both its text-based search and its structured query using this event, which takes a dictionary of strings:

getCurrentSession().query({ queryName: "product-search", query: { text: "stylish leggings", size: "12", color: "Blue" } );

Chat Prompts and Responses

If the user makes a query you can record it using this event, you can record both its text-based search and its structured query using this event, which takes a dictionary of strings:

getCurrentSession().chatPrompt({
  promptId: 'introduction',
  promptText:
    'Introduce the selected product to the user in a professional manner, the selected product is ...'
});

// ...submit prompt to LLM and get a response...

getCurrentSession().chatResponse({
  promptId: 'introduction',
  promptResponseText:
    'Hello and Welcome to eShop!  This electronic yak shaver you have selected is the perfect wedding gift...'
});

Errors

You can record any errors on the frontend to analytics, just pass in the error object (which must be derived from the JavaScript Error class):

const error = new Error('bad data encountered');
getCurrentSession().error(error);

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
});

Augmented Reality

When the user requests a augmented reality experience, two events can be sent. The first is to request an AR experience and then a second once that AR experience ia launched.

getCurrentSession().ar({
  arStage: ARStage.Offered,
  arHandoffId: userId
});

Personalize Text

When the user is personalizing an item with custom text, use this event:

getCurrentSession().personalizeText({
  personalizeId: 'Label Text',
  personalizedText: labelText
});

Parametric Value

When the user sets parametric values on an item, record those changes with this event:

getCurrentSession().parametricValue({
  parametricId: 'Table Width',
  parametricValue: tableWidth
});

Image Upload

When you allow a user to upload custom images, record those uploads with this event:

getCurrentSession().imageUpload({
  imageUploadId: 'Front Image',
  imageUploadFileId: fileID
});

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' });

Best Practices for Analytics Integration

To effectively leverage analytics, it's crucial to capture key user decisions during their interactions with your application. While each project may have unique requirements, the following guidelines can help ensure comprehensive tracking:

Capture Key Decision Points

Multi-Choice Options

• Record when users are presented with multiple choices and when they make a selection.
• Capture details such as:
  • The available options (SKUs, asset IDs, prices, etc.).
  • Prices associated with each option.
  • The option the user ultimately selected.

Stage Transitions

• Track when users advance to the next stage in a multi-step process, such as progressing through a configuration experience.
• Record when users move forward or go back to a previous stage.
• Ensure consistent naming for stages to maintain clarity.

Adding Products to Cart

• Capture details when items are added to the cart, including:
  • SKUs or asset IDs of the products.
  • Product names and prices.

Requesting Quotes or Purchases

• Record quote requests by capturing:
  • The total amount of the quote.
  • Item Ids and names and prices
  • Customer ID and order ID for reference.

Creating Share Links

• Track when a shareable link is generated by recording:
  • The URL of the shared configuration.

Ensure Consistency and Accuracy

Consistent Naming Conventions:

• Use standardized names for stages, options, and events across your application. This consistency simplifies data analysis and reporting.

Comprehensive Event Tracking:

• Avoid overlooking significant events. Think about the user journey and identify all critical interactions that should be recorded.

Testing and Validation:

• Before deploying, thoroughly test your analytics implementation to ensure all events are captured accurately. Validate that the data recorded aligns with user actions.

Support

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