Embed chart as web component / Tractorscope Docs

Embed TractorScope charts directly into your website using modern web components—no iframes required. This approach provides a seamless integration that feels native to your site while maintaining full functionality and interactivity.

Browser Compatibility: Web components are widely supported in modern browsers, but we recommend verifying compatibility for your specific use case. Check current browser support at Can I Use Web Components.

Installation

First, add the TractorScope embed script to your website:

<script src="https://app.tractorscope.com/embed/tractorscope-embed.js"></script>

<script src="https://app.tractorscope.com/embed/tractorscope-embed.js"></script>

Basic Usage

Once the script is installed, you can embed a chart by adding the custom element to your HTML:

<tractorscope-chart signature="your_signature_here"></tractorscope-chart>

<tractorscope-chart signature="your_signature_here"></tractorscope-chart>

Generating Signatures

The

signature

attribute authenticates your embed request and specifies which chart to display. You can generate signatures in two ways:

Through the TractorScope Dashboard: Generate signatures directly from the interface
Server-Side Generation: Create signatures programmatically using your API key

The signature format is identical for both web components and iframe embeds, so you can use the same generation method described in our Compose an embeddable URL documentation.

Dynamic Filtering

Web components support dynamic filtering through the signature. You can pass filter parameters to customize the chart data displayed. Below are examples in Node.js and Python:

Here are some samples of server side signature generation:

const { createHmac } = require("crypto");

// get your tractorscope API Key in the dashboard settings
const key = 'Your TractorScope API Key';

// the chart you want to embed
const chart = 'cht_01GRS8C4BVZ8X9N7E86Z82DQG9'

// compose the data object with filters and dashboard
const data = encodeURIComponent(
  JSON.stringify({
    chart,
    filters: {
      "Date Range": "last_month",
      "Aggregation": "day",
      "ClientId": "YourClientId",
      // more filters here
    },
  })
);

// compose final signature and base64 encode it to pass to the web component
return btoa(JSON.stringify({ 
  data, 
  signature: createHmac("sha256", key).update(data).digest("hex")
}));

const { createHmac } = require("crypto");

// get your tractorscope API Key in the dashboard settings
const key = 'Your TractorScope API Key';

// the chart you want to embed
const chart = 'cht_01GRS8C4BVZ8X9N7E86Z82DQG9'

// compose the data object with filters and dashboard
const data = encodeURIComponent(
  JSON.stringify({
    chart,
    filters: {
      "Date Range": "last_month",
      "Aggregation": "day",
      "ClientId": "YourClientId",
      // more filters here
    },
  })
);

// compose final signature and base64 encode it to pass to the web component
return btoa(JSON.stringify({ 
  data, 
  signature: createHmac("sha256", key).update(data).digest("hex")
}));

Styling and Layout

The embedded chart automatically adapts to its parent container's dimensions, providing a responsive experience that integrates naturally with your site's layout.

CORS and Security

When serving your embeds from your web application, you will want to configure CORS domains within Tractorscope to allow requests from your domain. This ensures that your embeds can securely fetch data without running into cross-origin issues. To manage domains you can do so under Tractorscope App → Settings → Domains. Add your domain to the list of allowed domains to ensure your embeds work correctly.

Note, if you are embedding charts on a public website, make sure to only share charts that contain non-sensitive data. The signature ensures that only charts you've explicitly shared can be embedded, but it's still important to be mindful of the data you're exposing.

Conclusion

With just a script tag and a signature, you can bring TractorScope's powerful analytics directly into your application. The web component approach offers better performance and deeper integration compared to traditional iframe embeds.

Happy embedding!