# Embeddable Widgets

> Embed TraceKit status widgets in your dashboards and status pages. Real-time service health, error rates, and performance metrics.

- Canonical: https://tracekit.dev/docs/widgets

# 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

## 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.

**Security Recommendation:** Always configure allowed domains for production widgets to prevent unauthorized embedding and potential abuse.

Example allowed domains:

```text
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:

```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.

```javascript
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.

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

### Uptime Widget

90-day uptime history visualization with incident timeline.

```javascript
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:

```javascript
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