Onpane

Self-Hosting

Serve the Onpane widget from your own domain instead of loading it from onpane.com. This is useful when your security policy requires all scripts to originate from first-party domains.

Download the Widget

  1. Sign in to your Onpane dashboard
  2. Open your project and go to Settings
  3. In the Self-Hosted Widget card, click Download Widget
  4. Place the downloaded onpane-widget.js file on your web server (e.g., at /js/onpane-widget.js)

Add to Your Site

Add the following script tag to your HTML, just before the closing </body> tag:

HTML
<script
  src="/js/onpane-widget.js"
  data-key="YOUR_API_KEY"
  data-api="https://onpane.com"
></script>
  • src — the path to the widget file on your server
  • data-key — your project API key from the dashboard (starts with onpane_live_)
  • data-api — the Onpane API URL. This attribute is required for self-hosted widgets so the widget knows where to fetch announcements and send analytics events.

V1 API Reference

The self-hosted widget calls the versioned API to fetch the active announcement and widget configuration.

Endpoint: GET /api/v1/widget/:key

Response shape:

JSON
{
  "announcement": {
    "id": "abc123",
    "title": "Maintenance Notice",
    "message": "Scheduled downtime tonight at 10 PM.",
    "type": "info",
    "ctaText": "Learn more",
    "ctaUrl": "https://example.com/status",
    "startDate": "2026-03-17T00:00:00Z",
    "endDate": null
  },
  "config": {
    "position": "top",
    "animation": "slide",
    "isDismissible": true,
    "fontSize": "medium",
    "fontFamily": null
  }
}

This response shape is stable. The V1 API will not introduce breaking changes, so your self-hosted widget will continue to work across updates.

Analytics

The self-hosted widget sends analytics events (views, clicks, and dismissals) back to the Onpane API. Events are sent to the origin specified by data-api, not the host page origin.

Analytics tracking is controlled by the Analytics Tracking toggle in your project settings. When disabled, the widget does not send any analytics events.

Updating the Widget

To update to the latest widget version, download a fresh copy from your project settings and replace the file on your server. There is no automatic update mechanism for self-hosted widgets — you control when updates are applied.