The Hark JavaScript API

Control the widget from your own code with window.Hark.open, close, identify, and setContext.

JavaScript API · 3 min read

Once the install script (see Embed install) has run, it defines window.Hark, a small object with four methods your page can call directly. There is no separate SDK to import; the methods are attached to the global window by the loader itself.

Availability

window.Hark is created when the loader script executes, so call these methods only after that script has had a chance to run. In practice this means calling them from your own application logic that already runs after page load (for example, once you know a user is signed in), rather than from a script tag that races the loader. A simple guard is enough if you are ever unsure:

if (window.Hark) {
  window.Hark.identify({ customerToken: signedToken })
}

Methods

Method	Signature	What it does
`open`	`Hark.open()`	Opens the widget panel, as if the visitor clicked the launcher.
`close`	`Hark.close()`	Closes the widget panel.
`identify`	`Hark.identify({ customerToken })`	Passes a signed identity token proving who the visitor is. See Signed identity.
`setContext`	`Hark.setContext({ page, plan, productArea, ... })`	Passes unauthenticated page context used for enrichment (greetings, routing hints).

window.Hark.open()
window.Hark.close()
window.Hark.identify({ customerToken: signedToken })
window.Hark.setContext({
  page: window.location.pathname,
  plan: 'pro',
  productArea: 'billing',
})

identify

identify only accepts an object with a string customerToken. Anything else is silently ignored. The token is the HMAC-signed identity token described in Signed identity, generated on your server, never in the browser. Calling identify marks the visitor as identified for the widget's audience-based visibility rules (an "identified only" launcher rule starts showing, for instance) and forwards the token into the widget iframe for verification.

setContext

setContext accepts any plain object and stores it as-is on the client; it is not validated beyond being an object. It is forwarded into the widget iframe, which parses it into a bounded, known-key subset (url, path, title, plan, productArea, locale, and a small set of string attributes) before using it. Because this data is never signed, it is treated purely as enrichment. It can shape a greeting or a routing hint, but it is never trusted as proof of identity, and it cannot substitute for identify.

The postMessage bridge

Under the hood, the host page and the widget iframe communicate over window.postMessage, scoped to the loader's resolved origin so messages never cross to an unrelated frame.

Outbound (host to widget). After you call identify or setContext, or whenever the widget is opened, the loader posts the current identity token and page context into the iframe:

frame.contentWindow.postMessage({ type: 'hark:identify', token: identityToken }, origin)
frame.contentWindow.postMessage({ type: 'hark:context', context: pageContext }, origin)

A proactive message that is configured to start a specific flow also posts a start instruction once the visitor clicks it:

frame.contentWindow.postMessage({ type: 'hark:start_flow', scenarioId }, origin)

Inbound (widget to host). The widget can ask the host page to close the panel, for example after a visitor dismisses it from inside the iframe:

// posted by the widget iframe; the host listens and calls setOpen(false)
window.postMessage('hark:widget:close', origin)

You do not need to wire up this bridge yourself. It exists so identify, setContext, and the widget's own close affordance work correctly; it is documented here so you understand what is moving between the frames if you are debugging with your browser's network or console tools.