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.

Use Cases

• Public status pages for customer visibility
• Documentation sites showing API health
• Marketing pages demonstrating reliability
• Partner portals displaying service availability
• Internal dashboards for team monitoring

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.

Security Recommendation

Always configure allowed domains for production widgets to prevent unauthorized embedding and potential abuse.

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>

Integration Notes

• The widget loads asynchronously and won't block page rendering
• Compatible with all modern browsers (Chrome, Firefox, Safari, Edge)
• Automatically updates in real-time without page refresh
• Works with static sites, React, Vue, Angular, and other frameworks

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
});

Option	Type	Description
theme	string	'light' \| 'dark' \| 'auto'
showUptime	boolean	Display uptime percentage
showResponseTime	boolean	Display average response time
refreshInterval	number	Auto-refresh interval (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