Subject: New Analytics API Implementation Guide

Hi,

We are rolling out a new centralized Analytics Engine for the backend. Please implement the event
tracking in the Flutter app following the specifications below.

1. The Core Strategy: Batching (Crucial)

Do NOT call the API on every single click. This will drain the user's battery and overload the server.

• Logic: Store events locally (in a list/queue) as the user interacts with the app.

• Trigger: Send the batch to the API only when:

1. The queue reaches 20 events.

2. OR a timer of 30 seconds expires.

3. OR the user minimizes/closes the app.

2. API Details

• Endpoint: POST {BASE_URL}/api/analytics/track

• Auth Header: Authorization: Bearer <JWT_TOKEN>

• Note: Do NOT send userId in the JSON body. The backend extracts it securely from the Token.

3. The Payload Structure

The backend expects a JSON Object containing an array of events.

Root JSON: code JSON

downloadcontent_copy

expand_less

"events": [

// ... list of event objects ...

Single Event Object Schema:

| Field | Type | Description |
| :--- | :--- | :--- |
| sessionId | String (GUID) | Generate one GUID when the App Launches. Use the same ID until the app is
killed. |
| eventCategory | String | See "Category Dictionary" below. |
| eventType | String | See "Event Dictionary" below. |
| timestamp | String | UTC ISO 8601 format (e.g., "2023-12-08T10:30:00Z"). |
| metaData | JSON Object | Flexible Key-Value pairs specific to the event. |

4. Event Dictionary (Copy these Exact Keys)

Please use these exact strings for eventCategory, eventType, and metaData keys.

A. Navigation (Screen Tracking)

When a user goes to a new page.

• Category: "Navigation"

• Type: "ScreenView"

• MetaData:

code JSON downloadcontent_copy

expand_less

"screenName": "Lesson_Junctions",

"previousScreen": "Dashboard",

"timeSpentSeconds": 45 // Calculate time spent on previous screen

B. Video Engagement

• Category: "Content"

• Start Event: Type = "VideoStart"

• Heartbeat (Send every 15s): Type = "VideoHeartbeat"

• Complete: Type = "VideoComplete"

• MetaData:

code JSON downloadcontent_copy

expand_less
 {

"contentId": 101, // The Video ID

"contentType": "Video",

"positionSeconds": 30, // Where are they now?

"totalDurationSeconds": 120,

"didSeek": false // True if they scrubbed the bar

C. Exams & Quizzes

• Category: "Assessment"

• Start Event: Type = "ExamStarted"

• Pass/Fail Event: Type = "ExamPassed" or "ExamFailed" • Drop-off Event: Type =

"ExamAbandoned" (User clicked back)

• MetaData: code JSON downloadcontent_copy expand_less

"examId": 5, // The ID of the Section/Subsection

"examType": "Section", // OR "Subsection" OR "Final" (Required to avoid ID collision)

"score": 85.5, // If completed

"attemptNumber": 2,

"wrongQuestionIds": "[10, 14]" // Optional: JSON array of failed IDs

D. User Clicks (Interactions)

• Category: "Interaction"

• Type: "Click"

• MetaData:

code JSON downloadcontent_copy

expand_less
 {

"screenName": "Home",

"elementName": "Btn_StartFreeTrial" // Specific name of the button

E. Commerce (Subscriptions)

• Category: "Commerce"

• Type: "PaywallHit" (User clicked a locked item) or "CheckoutStarted"

• MetaData:

code JSON downloadcontent_copy

expand_less

"triggerSource": "Locked_Lesson_Video", // Where did they click?

"planId": "Monthly_Pro"

5. Implementation Checklist for Mobile

1. Session Persistence: Ensure sessionId remains the same while the app is open. Regenerate it
only if the app is killed and restarted.

2. Offline Support: If the API fails or internet is lost, do not discard data. Save it to local storage
(Hive/SQLite) and retry sending when the internet returns.

3. App Lifecycle: Ensure any buffered events are flushed (sent) immediately when AppLifecycleState
changes to paused or detached.

Let me know if you have any questions about the metaData keys.

Thanks.
 Request Payload Schema
The API expects a root JSON object containing an array of events.

Master JSON Example

code JSON

downloadcontent_copy

expand_less

"events": [

"sessionId": "a4e8d8d0-99z1-4123-b321-userSessionId",

"eventCategory": "Navigation",

"eventType": "ScreenView",

"timestamp": "2023-12-08T10:00:00Z",

"metaData": {

"screenName": "Lesson_Junctions",

"previousScreen": "Dashboard",

"timeSpentSeconds": 45

},

"sessionId": "a4e8d8d0-99z1-4123-b321-userSessionId",

"eventCategory": "Assessment",

"eventType": "ExamPassed",

"timestamp": "2023-12-08T10:05:00Z",

"metaData": {

"examId": 10,

"examType": "Section",
 "score": 85.5,

"totalQuestions": 10

Field Definitions

Field Type Description

String Generate one UUID when the App Launches. Keep it constant until the app is
sessionId
(GUID) killed from memory.

eventCategory String Must match the Dictionary below.

eventType String Must match the Dictionary below.

timestamp String UTC ISO 8601 format (e.g., "2023-12-08T10:30:00Z").

JSON
metaData Flexible Key-Value pairs specific to the event type.
Object

4. Event Dictionary (Strict Schema)

Critical: You must use the exact String Values and Key Names listed below. The backend logic depends on
these specific keys to route data to the correct database tables.

A. Navigation & Flow

Tracks screen views and general usage.

Event
Event Type Required MetaData Keys
Category

screenName, previousScreen, timeSpentSeconds (Duration on previous

Navigation ScreenView
screen)

Interaction Click screenName, elementName (e.g., "Btn_Login")

B. Content Engagement

Tracks video watching and text lesson reading.

Event
Event Type Required MetaData Keys
Category

Content VideoStart contentId (Video ID), title

contentId, positionSeconds (Current time), totalDurationSeconds

Content VideoHeartbeat
<br>(Send this event every 15 seconds while playing)

Content VideoComplete contentId, didSeek (bool), playbackSpeed

Content LessonRead contentId (Lesson ID), scrollDepthPercent (0-100)

C. Assessments (Exams & Quizzes)

Tracks exam performance. Crucial: You must include examType to distinguish between Section and
Subsection exams.

Event Category Event Type Required MetaData Keys

examId, examType ("Section" / "Subsection" / "Final"),

Assessment ExamStarted
attemptNumber

Assessment ExamPassed examId, examType, score, totalQuestions

Assessment ExamFailed examId, examType, score, totalQuestions

Assessment QuestionFail examId, examType, questionId, selectedOptionId

Assessment ExamAbandoned examId, examType, questionsAnswered, lastQuestionId

D. Commerce (Subscriptions)

Tracks the purchase funnel.

Event
Event Type Required MetaData Keys
Category

triggerSource (e.g., "Locked_Lesson_Name" or

Commerce PaywallHit
"Profile_Upgrade_Btn")

Commerce CheckoutStarted planId, price

Commerce SubscriptionSuccess planId, transactionId, amount

Commerce CheckoutFailed errorReason

E. System & Search

Tracks technical health and user intent.

Event Category Event Type Required MetaData Keys

System Crash errorMessage, deviceModel, osVersion, batteryLevel

Search SearchPerformed searchTerm, resultCount

Search SearchResultClicked searchTerm, contentClickedId