Web Component embedding

circle-info

Target Audience: Developers

TL;DR

Toucan AI utilizes a standards-based web component to enable framework-agnostic embedding of analytics through a custom HTML element.


When to use this

Choose this method to maintain a portable analytics layer that works across any web stack—including React, Vue, Angular, or plain HTML—without requiring a dedicated SDK or complex build dependencies.


Functional Overview

The web component is a self-contained unit of code that wraps Toucan AI visualizations into a custom HTML tag. This approach leverages native browser technologies to ensure that dashboards and charts render consistently regardless of the host application's underlying framework.

<script type="module" src="https://toucanai.cloud/embed/embed.js"></script>
<tc-dashboard
    dashboard-id="your-dashboard-id"
    auth-token="your-embed-token"
    server-url="https://toucanai.cloud/api"
    data-theme="light"
    style="width: 100%; height: 600px;"
></tc-dashboard>

Core Attributes

The behavior and content of the web component are controlled through declarative HTML attributes:

Attribute
Required
Description

dashboard-id / chart-id

The unique identifier for the Toucan AI resource to render.

auth-token

A secure, server-generated JWT used for session authorization.

server-url

The API endpoint for your specific Toucan AI instance.

data-theme

Optional setting to toggle between "light" or "dark" modes.


Architectural Advantages

  • Framework Independence: The component runs natively in the browser, eliminating the risk of framework lock-in or version conflicts.

  • Zero Build Overhead: Integration requires no npm installations or specialized build-time configurations.

  • Encapsulated Logic: All rendering logic, data fetching, and interactivity are handled internally by the component.

  • Token-Driven Security: Access control is strictly managed through server-side generated tokens, protecting sensitive API keys.


Limitations

  • Interactivity Constraints: Advanced programmatic interactivity may require the SDK or API-driven methods.

  • Session Isolation: Authentication is limited to the embed token; the component does not share user sessions with the host application.

Last updated

Was this helpful?