Quickstart

Identify your customers and open the feedback widget in five minutes.

Harkly needs one thing from your app: who the customer is. Everything else — boards, roadmap, changelog, help center, messenger — is hosted and ready.

1. Get your public key

Sign in at app.harkly.app, create a workspace, and copy the public key from Settings → SDK & install. It starts with hk_pub_ and is safe to ship in a browser.

2. Install the SDK

npm install @harkly/js

Or drop in the script tag and skip the bundler:

<script src="https://cdn.harkly.app/v1/harkly.iife.js" defer></script>

3. Initialize and identify

import { init, identify } from "@harkly/js";

init({ publicKey: "hk_pub_…" });

// once you know who they are
identify({ id: user.id, email: user.email, name: user.name, plan: user.plan, mrr: user.mrr });

identify accepts any flat attributes; Harkly types them on first sight, so { seats: 3, beta: true } becomes filterable the moment it arrives. Pass a company too and votes are deduplicated per company.

4. Open a widget

import { feedback, updates, messenger } from "@harkly/js";

feedback({ board: "feature-requests" });   // the post form, as a modal
updates();                                 // the changelog panel with an unread badge
messenger();                               // the launcher, bottom-right

Your portal is live at https://<workspace>.harkly.app from the start; the widgets are the same pages inside an iframe, so a customer who posts from the widget can follow the thread on the portal.

5. Trust who they say they are

A public key can identify a person but can never change an email. To let Harkly trust an email change, sign a JWT with the workspace's SSO secret and pass it along:

identify(user, { jwt: await fetch("/api/harkly-token").then((r) => r.text()) });

The token is HS256, sub is the user id, and it is verified on every call. See Identity for the server side.

Next

  • React — <HarklyProvider>, <FeedbackButton>, <Messenger>
  • iOS and macOS — HarklyKit for SwiftUI
  • API — everything the dashboard can do, with a key
  • Self-hosting — one machine, ten minutes