Copy page

Core Concepts

Extension Kit Integration

This guide covers platform integration functions provided by the Teachfloor Extension Kit (@teachfloor/extension-kit).

What This Document Covers

This document focuses exclusively on API functions for platform integration:

Core Functions

• initialize() - Signal that your app is ready
• subscribeToEvent() - Listen to platform events
• store(), retrieve(), createCollection() - Data storage and retrieval
• showToast() - Display notifications
• showDrawer(), hideDrawer(), toggleDrawer() - Control app drawer
• goToViewport() - Navigate to different platform areas using viewports
• goToPath() - Navigate to different platform areas using paths

React Hooks

• useExtensionContext() - Access user and platform data reactively

Quick Reference

What you need	Where to find it
Events, Storage, Navigation, Toasts	This document (06-integration.md)
Buttons, Forms, Layouts, Charts	Extension Kit Components

Signaling App Ready

Basic Usage

Signal to the platform that your app is ready:

Code
import { initialize } from '@teachfloor/extension-kit'

function App() {
  useEffect(() => {
    initialize() // Signal app is ready
  }, [])

  return <div>My App</div>
}

With Context Provider

Code
import { ExtensionContextProvider } from '@teachfloor/extension-kit'

// The provider signals readiness automatically
<ExtensionContextProvider autoInit={true}>
  <App />
</ExtensionContextProvider>

API Reference

Events

Subscribe to Events

Listen to platform events using subscribeToEvent(). Events receive two parameters: the event data and an objectContext containing contextual information based on your app's permissions.

Code
import { subscribeToEvent } from '@teachfloor/extension-kit'

// Viewport changes - objectContext includes course/module/element based on permissions
subscribeToEvent('environment.viewport.changed', (viewport, objectContext) => {
  console.log('User navigated to:', viewport)

  if (objectContext.course) {
    console.log('Course:', objectContext.course.name)
  }
  if (objectContext.module) {
    console.log('Module:', objectContext.module.name)
  }
  if (objectContext.element) {
    console.log('Element:', objectContext.element.name)
  }
})

// Path changes - single parameter
subscribeToEvent('environment.path.changed', (path) => {
  console.log('Path changed:', path)
})

// User events - objectContext includes contextual data
subscribeToEvent('auth.user.event', (eventData, objectContext) => {
  console.log('User event:', eventData.type)

  if (objectContext.course) {
    console.log('Happened in course:', objectContext.course.name)
  }
})

Available Events:

Event	Parameters	Description
environment.viewport.changed	(viewport, objectContext)	User navigated to a different viewport. objectContext contains course/module/element data based on permissions.
environment.path.changed	(path)	URL path changed
auth.user.event	(eventData, objectContext)	User activity event (login, element_completed, quiz_submitted, etc.). objectContext contains contextual data.

objectContext Structure:

Code
interface ObjectContext {
  course?: {
    id: string
    object: 'course'
    name: string
    created_at: string
    cover: string | null
    availability: string
    visibility: string
    currency: string
    price: number | null
    metadata: object
  }
  module?: {
    id: string
    object: 'module'
    name: string
    created_at: string
    cover: string | null
    type: string
    position: number
    metadata: object
  }
  element?: {
    id: string
    object: 'element'
    name: string
    created_at: string
    cover: string | null
    type: string
    position: number
    metadata: object
  }
}

How it works:

Objects are included based on two conditions:

1. Permission granted: Your app must have the corresponding permission declared in the manifest
2. Relevant context: The current viewport/path must be within that context

When both conditions are met, the complete object is included. Otherwise, the key is not present in the object.

Example:

Code
// With course_read permission on a course detail page:
{
  course: { id: "abc123", name: "Introduction to React", /* ...other course fields */ }
  // module and element keys not present (not in their context)
}

// Without course_read permission on a course detail page:
{
  // No keys present (no permissions granted)
}

// With course_read and module_read on a module detail page:
{
  course: { id: "abc123", name: "Introduction to React", /* ...other course fields */ },
  module: { id: "def456", name: "Getting Started", /* ...other module fields */ }
  // element key not present (not in element context)
}

Data Storage

The Extension Kit provides store(), retrieve(), and createCollection() functions for persisting data. Three types of storage are available: app data (organization-wide), user data (user-specific), and user collections (paginated lists).

Context API

Accessing Context

Code
import { useExtensionContext } from '@teachfloor/extension-kit'

function MyComponent() {
  const { userContext, appContext, environment } = useExtensionContext()

  return (
    <div>
      <p>User: {userContext.full_name}</p>
      <p>App: {appContext.name}</p>
      <p>Viewport: {environment.viewport}</p>
    </div>
  )
}

Context Structure

Code
interface Context {
  userContext: {
    id: string
    created_at: string
    full_name: string
    email: string
    avatar: string
    language: string
    timezone: string
    identity_provider: {       // SSO/Identity provider details (null if not configured)
      provider: string         // Provider name (e.g., 'auth0', 'saml', 'neoncrm')
      user_id: string | null   // User ID in the identity provider
      user_metadata: object    // Additional user metadata from provider
    } | null
  }

  appContext: {
    id: string
    name: string
    version: string        // Current installed version
    permissions: string[]  // Array of granted permission scopes
    views: array           // Array of app view configurations from manifest
  }

  environment: {
    initialized: boolean
    viewport: string
    path: string
  }
}

Reactive Context

Context updates automatically when user data changes:

Code
function UserGreeting() {
  const { userContext } = useExtensionContext()

  // Re-renders when userContext changes
  return <h1>Hello, {userContext.full_name}!</h1>
}

UI Integration

Toast Notifications

Code
import { showToast } from '@teachfloor/extension-kit'

// Success message
showToast('Changes saved successfully', { color: 'green' })

// Error message
showToast('Failed to save changes', { color: 'red' })

// Info message
showToast('Processing your request', { color: 'blue' })

// Warning message
showToast('Please review your input', { color: 'orange' })

Options:

Code
interface ToastOptions {
  color?: 'green' | 'red' | 'blue' | 'orange'
  autoClose?: number  // milliseconds
}

Drawer Control

Code
import { showDrawer, hideDrawer, toggleDrawer } from '@teachfloor/extension-kit'

// Show drawer
function handleOpen() {
  showDrawer()
}

// Hide drawer
function handleClose() {
  hideDrawer()
}

// Toggle drawer
function handleToggle() {
  toggleDrawer()
}

// Auto-show on mount
useEffect(() => {
  showDrawer()
  return () => hideDrawer()
}, [])

Navigation

Code
import { goToViewport } from '@teachfloor/extension-kit'

// Navigate to courses
function goToCourses() {
  goToViewport('teachfloor.dashboard.course.list')
}

// Navigate to settings
function goToSettings() {
  goToViewport('teachfloor.dashboard.settings.general.detail')
}

// Navigate to account
function goToAccount() {
  goToViewport('teachfloor.dashboard.account.detail')
}

Deeplinking

Use goToPath when you already have a fully-resolved in-app path — typically captured from environment.path — and want to deeplink the user back to it (e.g. a saved bookmark or a "back to where you were" button).

Code
import { goToPath, useExtensionContext } from '@teachfloor/extension-kit'

// Save the current path...
const { environment } = useExtensionContext()
const savedPath = environment.path  // e.g. "/org-slug/courses/123/modules/456"

// ...and deeplink back later
goToPath(savedPath)

Rules and guards:

• path must be a relative path beginning with a single / (no protocol-relative //…, no absolute URLs). Anything else is ignored.
• The path must belong to the current organization — deeplinks whose first segment doesn't match the user's org slug are rejected, so an app installed in one org can't redirect the user into another.
• On custom domains, the org slug is stripped from the URL automatically — paths captured from environment.path work on both URL shapes.

AI Generation

Text Generation

Generate text using AI models with the platform's built-in AI capabilities.

Code
import { generate } from '@teachfloor/extension-kit'

// Generate text
async function generateContent() {
  try {
    const result = await generate(
      'Write a summary of this course',
      'ai/text-generate'
    )

    console.log(result) // Generated text response
    return result
  } catch (error) {
    console.error('Generation failed:', error)
  }
}

Parameters:

• prompt (string, required): The prompt to send to the AI model. Can include placeholders like {{course.content}}
• generationType (string, optional): Type of generation (default: 'ai/text-generate')

Available Generation Types:

• 'ai/text-generate': General text generation

Permissions Required:

• ai_text_generate: Always required to use AI generation
• ai_context_external_send: Only required when using placeholders
• Contextual permissions: Required for corresponding placeholders (course_read for course placeholders, etc.)

Using Placeholders

Include platform data directly in prompts using placeholders:

Code
import { generate } from '@teachfloor/extension-kit'

// Course placeholders (requires: ai_text_generate + course_read + ai_context_external_send)
const courseSummary = await generate(
  'Summarize this course: {{course.content}}'
)

// Module placeholders (requires: ai_text_generate + module_read + ai_context_external_send)
const moduleQuiz = await generate(
  'Create a 5-question quiz about {{module.name}}: {{module.content}}'
)

// Element placeholders (requires: ai_text_generate + element_read + ai_context_external_send)
const studyNotes = await generate(
  'Generate study notes for {{element.name}}: {{element.content}}'
)

Supported Placeholders:

• {{course.name}} - Course title
• {{course.content}} - Course content (text format)
• {{module.name}} - Module title
• {{module.content}} - Module content (text format)
• {{element.name}} - Element title
• {{element.content}} - Element content (text format)

Without Placeholders

You can also manually include context data (only requires ai_text_generate):

Code
import { generate, useExtensionContext } from '@teachfloor/extension-kit'

function SummarizeButton() {
  const { objectContext } = useExtensionContext()

  const handleSummarize = async () => {
    if (!objectContext.course) return

    // Manually including context - no placeholders
    const prompt = `Summarize this course:
      Name: ${objectContext.course.name}
      ID: ${objectContext.course.id}
    `

    const summary = await generate(prompt)
    console.log(summary)
  }

  return <button onClick={handleSummarize}>Generate Summary</button>
}

Error Handling:

Code
async function safeGenerate(prompt) {
  try {
    const result = await generate(prompt)
    return { success: true, data: result }
  } catch (error) {
    if (error.message === 'Teachfloor is not available') {
      return { success: false, error: 'Platform unavailable' }
    }
    return { success: false, error: error.message }
  }
}

Next Steps

→ Continue to Data Storage

Additional Resources

• Extension Kit Components - UI components reference
• Permissions - Permission scopes and usage
• Best Practices - Integration patterns and error handling
• Examples - Integration examples