Skip to content

Component Reference ​

The AddMapleEmbed component is the primary way to embed AddMaple widgets.

Installation ​

bash
npm install @addmaple/embed

Props ​

ts
interface AddMapleEmbedProps {
  /** REQUIRED - Function that returns dataset metadata + preview rows */
  getData: () => Promise<GetDataResponse>

  /** REQUIRED - Unique dataset identifier */
  datasetId: string

  /** REQUIRED - Viewer ID for analytics */
  userId: string

  /** REQUIRED - Which widget to render */
  widgetType: WidgetType

  /** REQUIRED - Receives structured lifecycle events */
  onAnalyticsEvent: (event: AnalyticsEvent) => void

  /** Optional - Override embed server (default: https://embed.addmaple.com) */
  serverBase?: string
}

type WidgetType = 'keyDrivers' | 'interestingColumns' | 'clustering' | 'aiChat' | 'all'

Required Props ​

getData ​

An async function that returns dataset metadata and preview rows. See getData() Contract for full documentation.

js
getData: async () => {
  const res = await fetch('/api/addmaple/data')
  return res.json()
}

datasetId ​

A unique, stable identifier for the dataset. This is used for caching and analytics.

js
datasetId: "dataset_123"

userId ​

The current viewer's ID. Used for analytics and personalization.

js
userId: "user_456"

widgetType ​

Which widget to render:

ValueDescription
keyDriversKey driver analysis widget
interestingColumnsInteresting columns discovery
clusteringData clustering visualization
aiChatAI-powered data chat
allAll widgets in a dashboard layout

onAnalyticsEvent ​

Callback that receives lifecycle events. See Analytics Events.

js
onAnalyticsEvent: (event) => {
  console.log(event.eventType, event.details)
  // Send to your analytics system
}

Optional Props ​

serverBase ​

Override the default embed server URL. Useful for enterprise deployments.

js
serverBase: "https://custom-embed.example.com"

Full Example ​

jsx
import ReactDOM from 'react-dom'
import AddMapleEmbed from '@addmaple/embed'

function App() {
  const handleAnalytics = (event) => {
    console.log('AddMaple event:', event)
    // Track in your analytics
    analytics.track('addmaple_event', event)
  }

  const getData = async () => {
    const res = await fetch('/api/addmaple/get-embed-data?datasetId=tf_123', {
      credentials: 'include'
    })
    if (!res.ok) throw new Error('Failed to get data')
    return res.json()
  }

  return (
    <AddMapleEmbed
      getData={getData}
      datasetId="tf_123"
      userId="user_456"
      widgetType="keyDrivers"
      onAnalyticsEvent={handleAnalytics}
    />
  )
}

ReactDOM.render(<App />, document.getElementById('root'))

TypeScript Support ​

The package includes TypeScript definitions:

ts
import AddMapleEmbed, { 
  AddMapleEmbedProps, 
  WidgetType, 
  AnalyticsEvent,
  GetDataResponse 
} from '@addmaple/embed'

Partner Documentation