A package for recording analytics from a front-end application.
- Record user interactions and events
- Track user selections and stage transitions
- Capture cart additions and purchase/quote events
- Log custom events for enhanced tracking
Install the package via your favorite package manager:
npm install @threekit/analyticsIt’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.
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
});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.
});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' });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" } );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...'
});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);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
});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
});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
});When the user is personalizing an item with custom text, use this event:
getCurrentSession().personalizeText({
personalizeId: 'Label Text',
personalizedText: labelText
});When the user sets parametric values on an item, record those changes with this event:
getCurrentSession().parametricValue({
parametricId: 'Table Width',
parametricValue: tableWidth
});When you allow a user to upload custom images, record those uploads with this event:
getCurrentSession().imageUpload({
imageUploadId: 'Front Image',
imageUploadFileId: fileID
});When the user generates a URL to share the configuration with another user, record the event using:
getCurrentSession().share({
shareLink: configurationUrl,
shareType: ShareType.Share
});For events in the user experience that don’t fit any predefined category, use a custom event:
getCurrentSession().custom({ customName: 'View Product List' });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:
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.
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.
For support and questions, please reach out to support@threekit.com.