Coven Documentation

Configuration reference for the OpenCoven Feedback widget: loader snippet, init options, identify shapes, and an allowlist pattern that restricts access to verified users.

The feedback widget ships as a CDN script or an npm package. Pick whichever fits your stack; both expose the same OpenCovenFeedback global.

Bare minimum

Add to your <head>. Anonymous visitors see the widget immediately after the script resolves.

<script>
  (function(w,d){if(w.OpenCovenFeedback)return;w.OpenCovenFeedback=function(){
  (w.OpenCovenFeedback.q=w.OpenCovenFeedback.q||[]).push(arguments)};
  var s=d.createElement('script');s.async=true;
  s.src='https://feedback.opencoven.ai/api/widget/sdk.js';
  d.head.appendChild(s)})(window,document);
  OpenCovenFeedback('init');
</script>

The IIFE guard (if(w.OpenCovenFeedback)return) prevents double-init on hot reloads or duplicate script includes.

Init options

OpenCovenFeedback('init', {
  placement: 'right',       // 'right' | 'left' — default 'right'
  defaultBoard: 'bugs',     // filter widget to one board slug
  launcher: true,           // false = hide the default floating button
  locale: 'en',             // override browser locale detection
  identity: { id, email, name }, // bundle an identify call into init
})

Theme colors and visible boards are configured in the OpenCoven admin panel under Settings → Widget, not in client code.

Identify a user

Call identify once you know who the user is. Skip it for anonymous sessions — the widget works without it.

// Unverified (client-side fields; no server check)
OpenCovenFeedback('identify', {
  id:    user.id,
  email: user.email,
  name:  user.name,
})

// Verified (server-signed JWT — recommended for allowlists)
OpenCovenFeedback('identify', { ssoToken: 'eyJ...' })

// Clear identity (anonymous mode; widget stays open)
OpenCovenFeedback('logout')

Allowlist — verified users only

To restrict the widget so only your own users can submit feedback, use the SSO token shape and call init with launcher: false. Then mount the launcher yourself once identity resolves.

// 1. Load without showing the launcher
OpenCovenFeedback('init', { launcher: false })

// 2. After auth resolves, identify with a server-signed token
async function mountFeedback(user) {
  const { token } = await fetch('/api/feedback-sso-token', {
    method: 'POST',
    headers: { Authorization: `Bearer ${user.accessToken}` },
  }).then(r => r.json())

  OpenCovenFeedback('identify', { ssoToken: token })
  OpenCovenFeedback('showLauncher')
}

The SSO token is a short-lived JWT minted on your server with the user's verified identity. Anyone without a valid token sees no launcher and cannot submit.

React pattern

'use client'

import { useEffect } from 'react'

interface WidgetUser {
  id: string
  email?: string
  name?: string
}

declare global {
  interface Window {
    OpenCovenFeedback?: (event: string, data?: object) => void
  }
}

/**
 * Drop anywhere in the tree after auth resolves.
 * - Renders nothing (returns null)
 * - Safe for anonymous users — does nothing when user is null
 */
export function WidgetIdentify({ user }: { user: WidgetUser | null | undefined }) {
  useEffect(() => {
    if (!user) return
    window.OpenCovenFeedback?.('identify', {
      id:    user.id,
      email: user.email,
      name:  user.name,
    })
  }, [user])

  return null
}

npm install

Skip the loader snippet if you prefer a module import:

npm install @opencoven/feedback-widget
# pnpm add @opencoven/feedback-widget
# bun add @opencoven/feedback-widget

import { OpenCovenFeedback } from '@opencoven/feedback-widget'

OpenCovenFeedback.init({ instanceUrl: 'https://feedback.opencoven.ai' })
OpenCovenFeedback.identify({ id: user.id, email: user.email, name: user.name })

Feedback widget