feat(app): Add livestream duration event (#20094)

Closes EXEC-2049

Author: mjhuff

app/src/pages/Desktop/LivestreamViewer/hooks/useReportWindowDurationEvent.ts

@@ -0,0 +1,79 @@
+import { useEffect, useState } from 'react'
+
+import { FLEX_ROBOT_TYPE } from '@opentrons/shared-data'
+
+import { isTerminalRunStatus } from '/app/organisms/Desktop/Devices/ProtocolRun/ProtocolRunHeader/utils'
+import {
+  SOURCE_RUN_RECORD,
+  useCameraAnalytics,
+} from '/app/redux-resources/analytics'
+
+import type { RunStatus } from '@opentrons/api-client'
+
+export function useReportWindowDurationEvent(
+  runId: string | null,
+  runStatus: RunStatus | null,
+  isLivestreamViewable: boolean
+): void {
+  const [streamStartTime, setStreamStartTime] = useState<number | null>(null)
+  const { reportLiveFeedDuration } = useCameraAnalytics({
+    source: SOURCE_RUN_RECORD,
+    robotType: FLEX_ROBOT_TYPE,
+  })
+
+  // On initial render or at the start of a new run, start the timer if the
+  // livestream is viewable.
+  useEffect(() => {
+    if (
+      runId != null &&
+      streamStartTime === null &&
+      !isTerminalRunStatus(runStatus) &&
+      isLivestreamViewable
+    ) {
+      const startTime = new Date().getTime()
+      setStreamStartTime(startTime)
+    }
+  }, [streamStartTime, runStatus, isLivestreamViewable, runId])
+
+  // If a run is terminal, we block livestream viewing, so send the event if the
+  // stream was enabled.
+  useEffect(() => {
+    if (
+      runId != null &&
+      isTerminalRunStatus(runStatus) &&
+      streamStartTime !== null
+    ) {
+      reportLiveFeedDuration({
+        runId,
+        durationSeconds: getDurationSeconds(streamStartTime),
+      })
+      setStreamStartTime(null)
+    }
+  }, [reportLiveFeedDuration, runId, runStatus, streamStartTime])
+
+  // If the user closes the window while a run is not terminal, report it if
+  // the stream was enabled.
+  useEffect(() => {
+    const handleBeforeUnload = (): void => {
+      if (
+        runId != null &&
+        !isTerminalRunStatus(runStatus) &&
+        streamStartTime !== null
+      ) {
+        reportLiveFeedDuration({
+          runId,
+          durationSeconds: getDurationSeconds(streamStartTime),
+        })
+      }
+    }
+
+    window.addEventListener('beforeunload', handleBeforeUnload)
+
+    return () => {
+      window.removeEventListener('beforeunload', handleBeforeUnload)
+    }
+  }, [reportLiveFeedDuration, runId, runStatus, streamStartTime])
+}
+
+const getDurationSeconds = (runStartTime: number): number =>
+  (new Date().getTime() - runStartTime) / 1000

app/src/pages/Desktop/LivestreamViewer/index.tsx

@@ -4,6 +4,7 @@ import { useTranslation } from 'react-i18next'
 import { Chip } from '@opentrons/components'
 
 import { useHlsVideo } from '/app/pages/Desktop/LivestreamViewer/hooks/useHlsVideo'
+import { useReportWindowDurationEvent } from '/app/pages/Desktop/LivestreamViewer/hooks/useReportWindowDurationEvent'
 import {
   LivestreamInfoScreen,
   useLivestreamInfoScreen,
@@ -44,6 +45,12 @@ export function LivestreamViewer(): JSX.Element {
     videoError
   )
 
+  useReportWindowDurationEvent(
+    retainedRunId,
+    runStatus,
+    cameraData?.liveStreamEnabled ?? false
+  )
+
   return (
     <div className={styles.container}>
       <div className={styles.video_container}>

app/src/pages/ODD/ProtocolSetup/__tests__/ProtocolSetup.test.tsx

@@ -351,6 +351,7 @@ describe('ProtocolSetup', () => {
         reportPhotoAccessUsage: vi.fn(),
         reportImageCaptureUsage: vi.fn(),
         reportLiveFeedUsage: vi.fn(),
+        reportLiveFeedDuration: vi.fn(),
       })
     vi.mocked(useScrollPosition).mockReturnValue({
       isScrolled: false,

app/src/redux-resources/analytics/hooks/useCameraAnalytics.ts

@@ -2,6 +2,7 @@ import {
   ANALYTICS_CAMERA_ENABLEMENT_KIND,
   ANALYTICS_CAMERA_SETTINGS_KIND,
   ANALYTICS_IMAGE_CAPTURE_KIND,
+  ANALYTICS_LIVE_FEED_DURATION,
   ANALYTICS_LIVE_FEED_KIND,
   ANALYTICS_PHOTO_ACCESS,
   useTrackEvent,
@@ -36,6 +37,9 @@ interface CaptureParams {
 interface LiveFeedParams {
   runId: string
 }
+interface LiveFeedDurationParams extends LiveFeedParams {
+  durationSeconds: number
+}
 interface MediaAccessParams {
   action: 'download' | 'downloadZip' | 'delete' | 'storageWarning'
   transactionId?: string
@@ -53,6 +57,8 @@ export interface UseCameraUsageAnalyticsResult {
   /* Reports how often images are downloaded together, seperately, 
   how often images are deleted, and how often storage warnings appear. */
   reportPhotoAccessUsage: (data: MediaAccessParams) => void
+  /* Reports the duration that the livestream was viewed for a particular session. */
+  reportLiveFeedDuration: (data: LiveFeedDurationParams) => void
 }
 
 export function useCameraAnalytics({
@@ -90,7 +96,6 @@ export function useCameraAnalytics({
       name: ANALYTICS_IMAGE_CAPTURE_KIND,
       properties: {
         robotType,
-        source,
         transactionId: data.transactionId,
         amount: data.amount,
       },
@@ -101,13 +106,22 @@ export function useCameraAnalytics({
     doTrackEvent({
       name: ANALYTICS_LIVE_FEED_KIND,
       properties: {
-        source,
         robotType,
         runId: data.runId,
       },
     })
   }
 
+  const reportLiveFeedDuration = (data: LiveFeedDurationParams): void => {
+    doTrackEvent({
+      name: ANALYTICS_LIVE_FEED_DURATION,
+      properties: {
+        runId: data.runId,
+        duration: `${data.durationSeconds} seconds`,
+      },
+    })
+  }
+
   const reportPhotoAccessUsage = (data: MediaAccessParams): void => {
     const baseProperties = {
       robotType,
@@ -128,6 +142,7 @@ export function useCameraAnalytics({
     reportCameraSettings,
     reportImageCaptureUsage,
     reportLiveFeedUsage,
+    reportLiveFeedDuration,
     reportPhotoAccessUsage,
   }
 }

app/src/redux/analytics/constants.ts

@@ -141,7 +141,10 @@ export const ANALYTICS_CAMERA_ENABLEMENT_KIND: 'cameraEnablementType' =
 export const ANALYTICS_CAMERA_SETTINGS_KIND: 'cameraSettingsKind' =
   'cameraSettingsKind'
 
-export const ANALYTICS_IMAGE_CAPTURE_KIND: 'imageCaptureKind' =
-  'imageCaptureKind'
-export const ANALYTICS_LIVE_FEED_KIND: 'liveFeed' = 'liveFeed'
-export const ANALYTICS_PHOTO_ACCESS: 'photoAccessKind' = 'photoAccessKind'
+export const ANALYTICS_IMAGE_CAPTURE_KIND: 'cameraImageCaptureKind' =
+  'cameraImageCaptureKind'
+export const ANALYTICS_LIVE_FEED_KIND: 'cameraLiveFeed' = 'cameraLiveFeed'
+export const ANALYTICS_PHOTO_ACCESS: 'cameraPhotoAccessKind' =
+  'cameraPhotoAccessKind'
+export const ANALYTICS_LIVE_FEED_DURATION: 'cameraLiveFeedDuration' =
+  'cameraLiveFeedDuration'