Tracks sandbox interactions for analytics

Implements event tracking for user interactions within the sandbox environment.

This change captures key interactions, such as clicks and hovers, to provide insights into user behavior and improve the sandbox experience. The data collected will inform decisions on sandbox discoverability, engagement, and overall user satisfaction.

Author: Younique98

src/components/interactive-lab-callout/index.tsx

@@ -10,6 +10,7 @@ import { useInstruqtEmbed } from 'contexts/instruqt-lab'
 import { FC } from 'react'
 import s from './interactive-lab-callout.module.css'
 import SANDBOX_CONFIG from 'content/sandbox/sandbox.json' assert { type: 'json' }
+import { trackSandboxInteraction } from 'views/sandbox-view'
 
 interface InteractiveLabCalloutProps {
 	labId?: string
@@ -34,6 +35,9 @@ const InteractiveLabCallout: FC<InteractiveLabCalloutProps> = ({ labId }) => {
 
 	const handleStartLab = () => {
 		if (effectiveLabId) {
+			trackSandboxInteraction('click', effectiveLabId, {
+				source: 'interactive-lab-callout',
+			})
 			ctx.openLab(effectiveLabId)
 			ctx.setActive(true)
 		} else {

src/components/lab-embed/embed-element/index.tsx

@@ -50,7 +50,7 @@ const EmbedElement = memo(function EmbedElement(): JSX.Element {
 		}))
 
 		if (labId) {
-			trackSandboxEvent(SANDBOX_EVENT.SANDBOX_LOADED, {
+			trackSandboxEvent(SANDBOX_EVENT.SANDBOX_OPEN, {
 				labId,
 				page: router.asPath,
 			})

src/components/navigation-header/components/sandbox-dropdown/index.tsx

@@ -23,6 +23,7 @@ import { SandboxLab } from 'types/sandbox'
 import { ProductSlug } from 'types/products'
 import { buildLabIdWithConfig } from 'lib/build-instruqt-url'
 import { useTheme } from 'next-themes'
+import { trackSandboxInteraction } from 'views/sandbox-view'
 
 interface SandboxDropdownProps {
 	ariaLabel: string
@@ -122,9 +123,6 @@ const SandboxDropdown = ({ ariaLabel, label }: SandboxDropdownProps) => {
 		}
 	}
 
-	/**
-	 * Handle lab selection
-	 */
 	const handleLabClick = (lab: SandboxLab) => {
 		const labWithTrack = {
 			...lab,
@@ -133,16 +131,13 @@ const SandboxDropdown = ({ ariaLabel, label }: SandboxDropdownProps) => {
 		const fullLabId = buildLabIdWithConfig(labWithTrack)
 		openLab(fullLabId)
 		setActive(true)
-		trackSandboxEvent(SANDBOX_EVENT.SANDBOX_STARTED, {
+		trackSandboxEvent(SANDBOX_EVENT.SANDBOX_OPEN, {
 			labId: fullLabId,
 			page: router.asPath,
 		})
 		setIsOpen(false)
 	}
 
-	/**
-	 * Navigate to the sandbox page
-	 */
 	const navigateToSandboxPage = (e: React.MouseEvent) => {
 		e.preventDefault()
 		router.push(`/${currentProduct.slug}/sandbox`)
@@ -230,7 +225,6 @@ const SandboxDropdown = ({ ariaLabel, label }: SandboxDropdownProps) => {
 						</Text>
 					</button>
 
-					{/* Available Product Sandboxes Section */}
 					<Text
 						asElement="p"
 						className={s.sectionTitle}
@@ -245,7 +239,12 @@ const SandboxDropdown = ({ ariaLabel, label }: SandboxDropdownProps) => {
 							<li key={lab.labId || index} className={s.itemContainer}>
 								<button
 									className={s.sandboxItem}
-									onClick={() => handleLabClick(lab)}
+									onClick={() => {
+										handleLabClick(lab)
+										trackSandboxInteraction('hover', lab.labId, {
+											page: router.asPath,
+										})
+									}}
 									onKeyDown={handleKeyDown}
 								>
 									<div className={s.content}>

src/components/sandbox-card/index.tsx

@@ -12,6 +12,7 @@ import CardFooter from 'components/card/components/card-footer'
 import ButtonLink from 'components/button-link'
 import ProductIcon from 'components/product-icon'
 import s from './sandbox-card.module.css'
+import { trackSandboxInteraction } from 'views/sandbox-view'
 
 export interface SandboxCardProps {
 	title: string
@@ -20,6 +21,7 @@ export interface SandboxCardProps {
 	products: string[]
 	onLaunch: () => void
 	className?: string
+	clickBehavior?: 'card' | 'button'
 }
 
 const SandboxCard: React.FC<SandboxCardProps> = ({
@@ -55,6 +57,7 @@ const SandboxCard: React.FC<SandboxCardProps> = ({
 						onClick={(e) => {
 							e.preventDefault()
 							e.stopPropagation()
+							trackSandboxInteraction('click', labId, { lab_title: title })
 							onLaunch()
 						}}
 						size="medium"

src/views/sandbox-view/index.tsx

@@ -36,6 +36,21 @@ interface SandboxPageProps {
 	availableSandboxes: SandboxLab[]
 	otherSandboxes: SandboxLab[]
 }
+export const trackSandboxInteraction = (
+	interactionType: string,
+	sandboxId: string,
+	additionalProps: Record<string, unknown> = {}
+) => {
+	if (typeof window !== 'undefined' && posthog?.capture) {
+		posthog.capture(SANDBOX_EVENT.SANDBOX_OPEN, {
+			interaction_type: interactionType,
+			sandbox_id: sandboxId,
+			...additionalProps,
+			timestamp: new Date().toISOString(),
+			page_url: window.location.href,
+		})
+	}
+}
 
 const trackSandboxPageError = (
 	errorType: string,
@@ -70,12 +85,17 @@ export const SandboxView = ({
 	const handleLabClick = useCallback(
 		(lab: SandboxLab) => {
 			try {
+				trackSandboxInteraction(SANDBOX_EVENT.SANDBOX_OPEN, lab.labId, {
+					lab_title: lab.title,
+					products: lab.products,
+				})
+
 				const primaryProduct = lab.products[0]
 				if (primaryProduct !== product.slug) {
 					// Redirect to the lab's primary product sandbox page with auto-launch
 					const targetUrl = `/${primaryProduct}/sandbox?launch=${lab.labId}`
 
-					trackSandboxEvent(SANDBOX_EVENT.SANDBOX_STARTED, {
+					trackSandboxEvent(SANDBOX_EVENT.SANDBOX_OPEN, {
 						labId: lab.labId,
 						page: targetUrl,
 					})
@@ -86,7 +106,7 @@ export const SandboxView = ({
 
 				if (hasConfigError) {
 					trackSandboxPageError(
-						'config_error_lab_launch',
+						SANDBOX_EVENT.SANDBOX_ERROR,
 						'Cannot launch lab due to configuration error',
 						{
 							lab_id: lab.labId,
@@ -106,7 +126,7 @@ export const SandboxView = ({
 
 				if (!openLab) {
 					trackSandboxPageError(
-						'open_lab_function_missing',
+						SANDBOX_EVENT.SANDBOX_ERROR,
 						'openLab function is not available',
 						{
 							lab_id: lab.labId,
@@ -128,7 +148,7 @@ export const SandboxView = ({
 
 				if (!embedLabId) {
 					trackSandboxPageError(
-						'missing_lab_id',
+						SANDBOX_EVENT.SANDBOX_ERROR,
 						'Lab embed ID is missing or invalid',
 						{
 							lab_id: lab.labId,
@@ -149,7 +169,7 @@ export const SandboxView = ({
 				openLab(embedLabId)
 				setActive(true)
 
-				trackSandboxEvent(SANDBOX_EVENT.SANDBOX_STARTED, {
+				trackSandboxEvent(SANDBOX_EVENT.SANDBOX_OPEN, {
 					labId: lab.labId,
 					page: `/${product.slug}/sandbox`,
 				})
@@ -236,7 +256,7 @@ export const SandboxView = ({
 			)
 		} catch (error) {
 			trackSandboxPageError(
-				'documentation_render_failed',
+				SANDBOX_EVENT.SANDBOX_ERROR,
 				'Failed to render sandbox documentation',
 				{
 					error_message: error instanceof Error ? error.message : String(error),
@@ -313,6 +333,7 @@ export const SandboxView = ({
 									labId={lab.labId}
 									products={lab.products}
 									onLaunch={() => handleLabClick(lab)}
+									clickBehavior="button"
 								/>
 							)
 						})}