This PR introduces Google Analytics to our browser extension. We have created a new SessionAnalyticsMachine.ts file which uses the XState library to manage the state of a user session and send relevant events to Google Analytics.
Detailed Description
The SessionAnalyticsMachine.ts file contains a state machine that manages the state of a user session. The state machine has two states: Idle and Active.
In the Idle state, the machine waits for a start_session event to transition to the Active state. When this event is received, a new session ID is generated, the session start time is recorded, and a notifyStartSession action is triggered to send a session_started event to Google Analytics.
In the Active state, the machine can handle transcribing, send_message, and end_session events. The transcribing event updates the total audio duration and the details of the last message. The send_message event increments the message count and sends a message_sent event to Google Analytics. The end_session event transitions the machine back to the Idle state and sends a session_ended event to Google Analytics.
The Google Analytics events contain various details about the session, such as the session ID, the total engagement time, the total audio duration, the total talk time, and the number of messages sent.
Events
The custom events sent to the analytics endpoint are as follows:
session_started: This event is sent when a new session starts. The event data includes:
session_id: A unique identifier for the session.
engagement_time_msec: The elapsed time since the session started, in milliseconds. For this event, it will always be 0.
transcription_mode: The transcription mode set by the user.
language: The language set by the user.
message_sent: This event is sent when a message is sent during an active session. The event data includes:
session_id: The unique identifier for the session.
engagement_time_msec: The elapsed time since the session started, in milliseconds.
transcription_mode: The transcription mode set by the user.
delay_msec: The delay in milliseconds between the end of the user's speech and the sending of the message.
wait_time_msec: The delay in milliseconds between the end of transcription and the sending of the message. This is the time spent waiting for additional user input, and is less than delay_msec.
talk_time_seconds: The number of seconds that the user spent speaking, from the start of the message to the end.
audio_duration_seconds: The number of seconds of user speech recorded. This will be less than or equal to talk_time_seconds, and is the duration of speech minus any whitespace (non-speaking parts) removed by the VAD.
rtf: Real-Time-Factor for this message. Values less than 1.0 are real-time.
session_ended: This event is sent when a session ends. The event data includes:
session_id: The unique identifier for the session.
engagement_time_msec: The total duration of the session, in milliseconds.
message_count: The total number of messages sent during the session.
duration_mins: The total duration of the session, in minutes.
audio_duration_seconds: The total duration of audio transcribed during the session, in seconds.
talk_time_seconds: The total duration of user speech during the session, in seconds.
How to Test
Unit tests have been added to verify the correct operation of the state machine and the correct triggering of Google Analytics events. To run the tests, use the command npm run test.
Impact
This change will allow us to gather valuable data about how users interact with our browser extension, which will inform future development decisions.
Screenshots
Splash screen informing users about the change, and their options.
This PR introduces Google Analytics to our browser extension. We have created a new
SessionAnalyticsMachine.tsfile which uses the XState library to manage the state of a user session and send relevant events to Google Analytics.Detailed Description
The
SessionAnalyticsMachine.tsfile contains a state machine that manages the state of a user session. The state machine has two states:IdleandActive.In the
Idlestate, the machine waits for astart_sessionevent to transition to theActivestate. When this event is received, a new session ID is generated, the session start time is recorded, and anotifyStartSessionaction is triggered to send asession_startedevent to Google Analytics.In the
Activestate, the machine can handletranscribing,send_message, andend_sessionevents. Thetranscribingevent updates the total audio duration and the details of the last message. Thesend_messageevent increments the message count and sends amessage_sentevent to Google Analytics. Theend_sessionevent transitions the machine back to theIdlestate and sends asession_endedevent to Google Analytics.The Google Analytics events contain various details about the session, such as the session ID, the total engagement time, the total audio duration, the total talk time, and the number of messages sent.
Events
The custom events sent to the analytics endpoint are as follows:
session_started: This event is sent when a new session starts. The event data includes:session_id: A unique identifier for the session.engagement_time_msec: The elapsed time since the session started, in milliseconds. For this event, it will always be 0.transcription_mode: The transcription mode set by the user.language: The language set by the user.message_sent: This event is sent when a message is sent during an active session. The event data includes:session_id: The unique identifier for the session.engagement_time_msec: The elapsed time since the session started, in milliseconds.transcription_mode: The transcription mode set by the user.delay_msec: The delay in milliseconds between the end of the user's speech and the sending of the message.wait_time_msec: The delay in milliseconds between the end of transcription and the sending of the message. This is the time spent waiting for additional user input, and is less thandelay_msec.talk_time_seconds: The number of seconds that the user spent speaking, from the start of the message to the end.audio_duration_seconds: The number of seconds of user speech recorded. This will be less than or equal totalk_time_seconds, and is the duration of speech minus any whitespace (non-speaking parts) removed by the VAD.rtf: Real-Time-Factor for this message. Values less than 1.0 are real-time.session_ended: This event is sent when a session ends. The event data includes:session_id: The unique identifier for the session.engagement_time_msec: The total duration of the session, in milliseconds.message_count: The total number of messages sent during the session.duration_mins: The total duration of the session, in minutes.audio_duration_seconds: The total duration of audio transcribed during the session, in seconds.talk_time_seconds: The total duration of user speech during the session, in seconds.How to Test
Unit tests have been added to verify the correct operation of the state machine and the correct triggering of Google Analytics events. To run the tests, use the command
npm run test.Impact
This change will allow us to gather valuable data about how users interact with our browser extension, which will inform future development decisions.
Screenshots
Splash screen informing users about the change, and their options.
GA4 console showing test data collection.