Skip to main content
Get Started
Documentation

Embed a Tractorscope chart as a web component

Embed Tractorscope charts directly into your website using modern web components. 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:
  1. Through the Tractorscope dashboard: Generate signatures directly from the interface
  2. 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 analytics directly into your application. The web component approach offers better performance and deeper integration compared to traditional iframe embeds.
Happy embedding!

FAQ

When should I use a web component instead of an iframe embed?

Use the web component when you want to place a single chart directly into your application layout. Use an iframe embed when you want to share a full dashboard experience with Tractorscope navigation and layout intact.

Does the chart signature need to be generated on the server?

Yes. The signature should be generated on the server so your API key stays private.

Can I pass filters to a web component embed?

Yes. Filters are part of the signed payload and let you tailor the embedded chart for a specific customer, user, date range, or aggregation level.

Do web component embeds use the same signing format as dashboard embeds?

Yes. The signing approach is the same. The main difference is whether the payload identifies a chart or a dashboard.

Related docs