Embeddable Widgets

Embed real-time service health status badges on your website, documentation, or status pages.

What are TraceKit Widgets?

TraceKit widgets are embeddable HTML components that display real-time health metrics for your services. They allow you to showcase service uptime, response times, and status information on external websites, documentation pages, or customer-facing dashboards.

Creating a Widget Key

Widget keys are API keys that authenticate and authorize widget embeds. Create them through your TraceKit dashboard:

1. Navigate to Settings -- Go to Settings -> Widgets in your TraceKit dashboard
2. Configure Widget Settings -- Provide a descriptive name, select service scope, and configure security options
3. Generate Embed Code -- Copy the generated HTML/JavaScript snippet to embed on your website

Service Scope

Control which services are displayed in your widget:

• All Services -- Widget displays health metrics for all services in your account. Ideal for comprehensive status pages.
• Specific Service -- Widget shows metrics for a single service. Perfect for documentation pages or service-specific dashboards.

Domain Restrictions

Enhance security by restricting which domains can embed your widgets. This prevents unauthorized use of your widget keys.

Example allowed domains:

https://example.com
https://docs.example.com
https://status.example.com

Leave empty to allow embedding on any domain (not recommended for production).

Rate Limiting

Each widget key has configurable rate limits to protect your TraceKit infrastructure and ensure fair usage.

• Default Rate Limit: 60 requests/min
• Configurable Range: Adjust based on your traffic needs

Rate limits are enforced per widget key. If exceeded, requests will receive a 429 Too Many Requests response.

Embedding the Widget

After creating a widget key, you'll receive an embed code snippet. Add it to your HTML:

<!-- TraceKit Widget -->
<div id="tracekit-widget"></div>
<script src="https://app.tracekit.dev/static/js/tracekit-widgets.js"></script>
<script>
  TraceKit.badge({
    apiKey: 'your_widget_api_key_here',
    serviceName: 'my-service',
    container: '#tracekit-widget'
  });
</script>

Widget Types

TraceKit supports multiple widget display formats:

Badge Widget

Compact status badge showing service health with uptime percentage and response time.

TraceKit.badge({
  apiKey: 'your_widget_api_key_here',
  serviceName: 'my-service',
  container: '#tracekit-widget'
});

Status Widget

Detailed status display with service list, metrics, and historical data.

TraceKit.status({
  apiKey: 'your_widget_api_key_here',
  container: '#tracekit-status',
  showHistory: true
});

Uptime Widget

90-day uptime history visualization with incident timeline.

TraceKit.uptime({
  apiKey: 'your_widget_api_key_here',
  serviceName: 'my-service',
  container: '#tracekit-uptime',
  days: 90
});

Customization Options

Customize widget appearance to match your brand:

TraceKit.badge({
  apiKey: 'your_widget_api_key_here',
  serviceName: 'my-service',
  container: '#tracekit-widget',
  theme: 'dark',
  showUptime: true,
  showResponseTime: true,
  refreshInterval: 60  // seconds
});

Security Best Practices

• Use domain restrictions -- Configure allowed domains to prevent unauthorized embedding
• Rotate widget keys periodically -- Update widget keys every 6-12 months for enhanced security
• Monitor usage metrics -- Review widget usage in Settings -> Widgets to detect anomalies
• Use separate keys per website -- Create individual widget keys for each domain for better tracking and isolation

Troubleshooting

Widget not displaying

• Check browser console for CORS errors (verify domain restrictions)
• Ensure widget script is loaded before TraceKit.badge() call
• Verify container element exists in DOM
• Confirm widget API key is active in Settings -> Widgets

429 Rate limit errors

• Increase rate limit in widget settings
• Implement client-side caching with refreshInterval option
• Check for multiple widget instances using same key

Data not updating

• Verify service is actively sending telemetry data
• Check widget refreshInterval setting
• Clear browser cache and reload page