Skip to content

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>
}

Lifecycle Events ​

Initialization ​

EventWhenDetails
initComponent mounted{}
getData_startCalling getData(){}
getData_completegetData() succeeded{ columns: [...], previewRowCount: 150 }
getData_errorgetData() failed{ error: "..." }
readyWidget ready for interaction{ mode: "browser" }

Analysis Events ​

EventWhenDetails
run_startAnalysis started{ mode: "browser" | "server", widget: "keyDrivers" }
run_completeAnalysis finished{ mode: "...", durationMs: 1234 }
run_errorAnalysis failed{ mode: "...", error: "..." }

Server Mode Events ​

EventWhenDetails
server_fetch_requestedUser requested server analysis{ urlProvided: true }
server_fetch_startAddMaple fetching full data{ url: "..." }
server_fetch_completeFull data received{ rowCount: 5000 }
server_fetch_failedFetch failed{ error: "...", statusCode: 403 }
fallback_browserFalling back to browser mode{ reason: "no_server_fetch" }
EventWhenDetails
consent_shownConsent dialog displayed{ type: "server_mode" }
consent_grantedUser granted consent{ type: "server_mode" }
consent_declinedUser declined consent{ type: "server_mode" }

Interaction Events ​

EventWhenDetails
widget_expandedWidget expanded{ widget: "keyDrivers" }
widget_collapsedWidget collapsed{ widget: "keyDrivers" }
column_selectedUser selected a column{ column: "satisfaction" }
chat_message_sentAI chat message sent{ messageLength: 42 }
export_clickedExport 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
  }
}

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.length

Alert on Errors ​

Set up alerts for:

  • run_error events above threshold
  • server_fetch_failed events (may indicate URL/auth issues)
  • getData_error events (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.length

Partner Documentation