Help by DeltaBreen for React

The support form, a logged-in user's own tickets, the Help button and your help articles as React components, for React 18 and later and Next.js. They draw Help's own elements and load our hosted script once, so your site gets our fixes without a release of yours. No dependencies besides React.

npm install @deltabreen/help-react

The form

import { HelpProvider, SupportForm } from '@deltabreen/help-react'

export default function App() {
  return (
    <HelpProvider siteKey="pk_live_…">
      <SupportForm subject="Book a call" fields={{ order_id: 'A-100' }} onSent={({ number }) => console.log(number)} />
    </HelpProvider>
  )
}

Your site's key is on its Install tab in the portal. Use the test key (pk_test_…) while you try things out: it works on any page, localhost too. The live key works only on your site's verified domains and its test domains.

Put HelpProvider once, around everything that shows Help. In Next.js's App Router the components are client components already ('use client'), so put the provider in your root layout.

| Component | Element | Props beside accent, labels, lang, siteKey, className, style | |---|---|---| | SupportForm | <db-help-form> | subject (true, or words to start it with), suggest={false}, fields, login, thanks, onSent, onError, onArticle, onAnswered | | MyTickets | <db-help-tickets> | login, onReplied, onClosed (they marked one solved), onRated, onUnread, onView (the ticket open in it, null for the list) | | HelpButton | <db-help-launcher> | position="left", login, onSent, onUnread | | HelpArticles | <db-help-articles> | section, inline, contact, onArticle, onAnswered |

login is where "Log in to send a message" and "Log in to see your tickets" lead, on a site that takes messages only from logged-in users: your login page, best with a way back (login="/login?return=/support"). thanks is your own thank-you page, opened once a message is sent; {number} in it becomes the ticket's number (thanks="/thank-you/?ticket={number}").

labels takes any of the element's words by name, as { title: 'Talk to us', emailHint: 'Your work email' }. The names are in the embed's guide.

Logged-in users

Your server signs a short token that says who is logged in, with the secret from your site's Install tab (see @deltabreen/help-server). Give the provider a function that fetches it, and null while nobody is logged in:

<HelpProvider siteKey="pk_live_…" identity={user ? () => fetch('/help-token').then((r) => r.text()) : null}>

It is asked each time the form needs a fresh token. Or give an address on your own site with identityUrl="/help-token".

Without the form

import { useDeltaHelp, useUnread } from '@deltabreen/help-react'

const help = useDeltaHelp()          // null until the script has started
await help?.submit({ email, body })  // rejects with a HelpError that has a stable `code`
const unread = useUnread()           // replies the logged-in user hasn't read
help?.refresh()                      // ask for new replies now, e.g. when your own code hears of one

context and fields on the provider are setContext and setFields: facts for your team, and values for the form's own fields on every form.

Proving your domain

Check your site on the Install tab reads your home page as your server sends it, before any script runs. A component adds nothing there, so give the proof another way:

• Next.js: export const metadata = { other: { 'deltabreen-help': 'deltabreen-help=…' } } in your root layout, with the value from the Install tab's tag.
• Vite or Create React App: the <meta name="deltabreen-help" content="…"> line from the Install tab, in index.html.
• Anywhere: the DNS record or the file, from the same step.

Content-Security-Policy

script-src  https://help.deltabreen.eu
connect-src https://help.deltabreen.eu