DocumentationWeb

Web integration

Add feedback to any website.

A zero-dependency widget rendered locally in Shadow DOM. Add the trigger, open the form yourself, or use the hosted page.

JavaScript / TypeScriptv0.2.0View on npm

Before you begin

A project, a key, and your app.

Create a project in Heardock and copy its hd_pub_ publishable key. The key identifies the project and is safe to include in your client.

Create a project
  • A Website project in Heardock
  • A browser environment
  • Your hd_pub_ key
01

Install the package

Install the SDK in your site or web app. It has no runtime dependencies and includes TypeScript declarations.

terminal
npm install heardock
02

Initialize the widget

Call init() in the browser after document.body is available. The trigger and form render locally; no remote UI loads when the dialog opens.

feedback.js
import { init } from 'heardock';

const feedback = init({
  key: 'hd_pub_your_key',
  label: 'Send feedback',
  placement: 'bottom-right',
  offset: { x: 20, y: 20 },
  transition: 'morph',
});
  • feedback.open(), close(), and destroy() give you programmatic control.
  • Call destroy() when the owning component unmounts.
  • The publishable key is safe in browser code; never use a secret key.
03

Use it with React or Next.js

Initialize once inside an effect so the widget is only created in the browser and is cleaned up with the component.

feedback-widget.tsx
'use client';

import { useEffect } from 'react';
import { init } from 'heardock';

export function FeedbackWidget() {
  useEffect(() => {
    const feedback = init({
      key: 'hd_pub_your_key',
      placement: 'bottom-right',
      transition: 'morph',
    });

    return () => feedback.destroy();
  }, []);

  return null;
}
04

Match your product

Choose a light or dark base palette, override individual colors, and localize only the strings you need. Unspecified strings keep the selected language defaults.

feedback-theme.js
const feedback = init({
  key: 'hd_pub_your_key',
  locale: 'zh-CN',
  strings: {
    title: '告诉我们你的想法',
    send: '提交',
  },
  theme: {
    mode: 'dark',
    primaryColor: '#ff9276',
    primaryTextColor: '#252b29',
    backgroundColor: '#171717',
    borderRadius: 16,
  },
});
05

Or embed without npm

For a plain HTML site, the CDN script adds a trigger and opens the hosted form in an iframe. You can also link directly to /f/<key>.

index.html
<script
  src="https://heardock.com/heardock-widget.js"
  data-key="hd_pub_your_key"
  data-label="Send feedback"
  defer
></script>

Verify the integration

Send one note. Check the whole loop.

  • Open the form and select a category.
  • Submit a short test message from a debug build.
  • Confirm the note and its context appear in your Heardock inbox.
  • Confirm the widget shows its success state and can be opened again.
Open the inbox
Next integrationiOS with Swift