Appearance
Analytics Events
The onAnalyticsEvent callback receives structured lifecycle events from the embed.
Event Structure
ts
interface AnalyticsEvent {
eventType: string
timestamp: string
datasetId: string
userId: string
widgetType: string
details?: Record<string, any>
}1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
Lifecycle Events
Initialization
| Event | When | Details |
|---|---|---|
init | Component mounted | {} |
getData_start | Calling getData() | {} |
getData_complete | getData() succeeded | { columns: [...], previewRowCount: 150 } |
getData_error | getData() failed | { error: "..." } |
ready | Widget ready for interaction | { mode: "browser" } |
Analysis Events
| Event | When | Details |
|---|---|---|
run_start | Analysis started | { mode: "browser" | "server", widget: "keyDrivers" } |
run_complete | Analysis finished | { mode: "...", durationMs: 1234 } |
run_error | Analysis failed | { mode: "...", error: "..." } |
Server Mode Events
| Event | When | Details |
|---|---|---|
server_fetch_requested | User requested server analysis | { urlProvided: true } |
server_fetch_start | AddMaple fetching full data | { url: "..." } |
server_fetch_complete | Full data received | { rowCount: 5000 } |
server_fetch_failed | Fetch failed | { error: "...", statusCode: 403 } |
fallback_browser | Falling back to browser mode | { reason: "no_server_fetch" } |
Consent Events
| Event | When | Details |
|---|---|---|
consent_shown | Consent dialog displayed | { type: "server_mode" } |
consent_granted | User granted consent | { type: "server_mode" } |
consent_declined | User declined consent | { type: "server_mode" } |
Interaction Events
| Event | When | Details |
|---|---|---|
widget_expanded | Widget expanded | { widget: "keyDrivers" } |
widget_collapsed | Widget collapsed | { widget: "keyDrivers" } |
column_selected | User selected a column | { column: "satisfaction" } |
chat_message_sent | AI chat message sent | { messageLength: 42 } |
export_clicked | Export button clicked | { format: "csv" } |
Example Handler
js
function handleAnalyticsEvent(event) {
console.log(`[AddMaple] ${event.eventType}`, event.details)
// Track in your analytics system
switch (event.eventType) {
case 'ready':
analytics.track('addmaple_widget_ready', {
datasetId: event.datasetId,
mode: event.details.mode
})
break
case 'run_complete':
analytics.track('addmaple_analysis_complete', {
datasetId: event.datasetId,
mode: event.details.mode,
duration: event.details.durationMs
})
break
case 'run_error':
case 'server_fetch_failed':
analytics.track('addmaple_error', {
datasetId: event.datasetId,
error: event.details.error
})
// Alert your monitoring system
Sentry.captureMessage('AddMaple error', { extra: event })
break
}
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
Monitoring Recommendations
Track Success Rate
js
// Calculate success rate
const events = getRecentEvents()
const runs = events.filter(e => e.eventType === 'run_start')
const successes = events.filter(e => e.eventType === 'run_complete')
const successRate = successes.length / runs.length1
2
3
4
5
2
3
4
5
Alert on Errors
Set up alerts for:
run_errorevents above thresholdserver_fetch_failedevents (may indicate URL/auth issues)getData_errorevents (may indicate backend issues)
Track User Engagement
js
// Engagement metrics
const engaged = events.filter(e =>
['column_selected', 'chat_message_sent', 'export_clicked'].includes(e.eventType)
)
const engagementRate = engaged.length / uniqueUsers.length1
2
3
4
5
2
3
4
5