React

# .env.local — both values are public, and both end up in the bundle.
VITE_HELPWING_SRC=https://api.helpwing.app/widget.js
VITE_HELPWING_PROJECT_KEY=pk_your_project_key

// src/support.ts
export interface SupportIdentity {
  /** Your own user id. Max 120 characters. */
  id: string
  email?: string
  /** Max 150 characters. */
  name?: string
  /** Hex HMAC-SHA256 of `id`, computed on your server. Never in the browser. */
  userHash?: string
  metadata?: Record<string, string | number | boolean>
}

interface SupportApi {
  identify(identity: SupportIdentity | null): void
  open(): void
  close(): void
  show(): void
  hide(): void
  /** Calls made before the script booted. The widget replays them on load. */
  q?: [string, unknown][]
}

declare global {
  interface Window {
    Support?: Partial<SupportApi>
  }
}

const SRC = globalThis._importMeta_.env.VITE_HELPWING_SRC
const PROJECT_KEY = globalThis._importMeta_.env.VITE_HELPWING_PROJECT_KEY

/** Adds the script tag. Safe to call twice; the second call does nothing. */
export function loadSupportWidget(): void {
  if (typeof document === 'undefined' || !PROJECT_KEY) return
  if (document.querySelector('script[data-project]')) return

  // The tag is async, so window.Support usually does not exist yet when the
  // first identify() runs. Seed the queue the widget drains on boot.
  window.Support ??= { q: [] }

  const script = document.createElement('script')
  script.async = true
  script.src = SRC
  script.dataset.project = PROJECT_KEY
  document.head.appendChild(script)
}

function invoke(method: keyof SupportApi, payload?: unknown): void {
  const support = window.Support
  if (!support) return
  const fn = support[method]
  if (typeof fn === 'function') (fn as (arg?: unknown) => void)(payload)
  else support.q?.push([method, payload])
}

export const support = {
  identify: (identity: SupportIdentity | null) => invoke('identify', identity),
  open: () => invoke('open'),
  close: () => invoke('close'),
  show: () => invoke('show'),
  hide: () => invoke('hide'),
}

// src/useSupportWidget.ts
import { useEffect } from 'react'
import { loadSupportWidget, support } from './support'
import type { SupportIdentity } from './support'

/**
 * Call once, from a component that lives for the whole session — the shell
 * around your router, not a page.
 *
 * Two effects rather than one: the script is added on mount and never again,
 * while the identity is re-sent whenever it changes. Neither returns a
 * cleanup. There is nothing to unmount — the widget is not part of your tree,
 * and removing its tag would throw away the visitor's open conversation.
 */
export function useSupportWidget(identity: SupportIdentity | null): void {
  useEffect(() => {
    loadSupportWidget()
  }, [])

  useEffect(() => {
    // identify(null) is how the widget forgets someone. There is no separate
    // reset, and the visitor keeps their history either way.
    support.identify(identity)
  }, [identity])
}

// src/App.tsx
import { useMemo } from 'react'
import { useAuth } from './auth'
import { useSupportWidget } from './useSupportWidget'

export default function App() {
  const { user } = useAuth()

  // Memoised: a fresh object literal on every render is a new dependency
  // every render, and the effect above would fire each time. The widget
  // deduplicates identical payloads before it talks to the server, so this
  // is about your own render loop rather than about request volume.
  const identity = useMemo(
    () =>
      user
        ? {
            id: user.id,
            email: user.email,
            name: user.name,
            userHash: user.supportUserHash,
            metadata: { plan: user.plan },
          }
        : null,
    [user],
  )

  useSupportWidget(identity)

  return <Router />
}

// Anywhere the launcher is not the obvious next step — a support entry in a
// menu, an empty state, a failed payment.
import { support } from '../support'

export function TalkToUs() {
  return (
    <button type="button" onClick={() => support.open()}>
      Talk to us
    </button>
  )
}

// app/support-widget.tsx
'use client'

import Script from 'next/script'
import { useEffect } from 'react'
import { useSession } from './session'

export function SupportWidget() {
  const { user } = useSession()

  useEffect(() => {
    const payload = user
      ? { id: user.id, email: user.email, name: user.name, userHash: user.supportUserHash }
      : null

    // The Script below has almost certainly not run yet on first paint, so
    // seed the queue here rather than assuming window.Support is the API.
    window.Support ??= { q: [] }
    const identify = window.Support.identify
    if (identify) identify(payload)
    else window.Support.q?.push(['identify', payload])
  }, [user])

  return (
    <Script
      src={process.env.NEXT_PUBLIC_HELPWING_SRC!}
      data-project={process.env.NEXT_PUBLIC_HELPWING_PROJECT_KEY!}
      strategy="lazyOnload"
    />
  )
}

// app/layout.tsx — a server component, which is why the one above says
// 'use client'. Mounted in the layout, the widget survives every navigation.
import { SupportWidget } from './support-widget'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <SupportWidget />
      </body>
    </html>
  )
}