Install the JavaScript SDK

The JS SDK is how Herald sees what users do inside your product. One <script> tag, one init call, events land in your Durable Object within seconds.

Install

<script src="https://sdk.withherald.co/v1/h.js" defer></script>
<script>
  window.herald = window.herald || [];
  window.herald.push(['init', { key: 'pk_live_xxx' }]);
</script>

Paste this into your app’s root layout. Your public key lives in Settings → SDK — it’s safe to ship to browsers.

Identify the user

Call identify as soon as you know who the user is. Herald joins events to user_entities by this id.

window.herald.push(['identify', {
  id: 'user_42',
  email: 'alex@helpkit.com',
  traits: { plan: 'team', seats: 5 },
}]);

Use a stable internal id — not an email. Emails change; user ids don’t.

Track an event

window.herald.push(['track', 'account_created', {
  source: 'marketing_site',
  plan_selected: 'trial',
}]);

Keep event names snake_case verbs in the past tense: account_created, invite_sent, export_completed. Stable names are worth more than clever ones — the briefing gets sharper every week you don’t rename them.

Server-side

For events that shouldn’t depend on a browser — trial conversion, invoice paid, webhook-triggered signups — use the server SDK with your server key (sk_live_xxx, not the public key).

import { Herald } from '@herald/sdk-server';

const herald = new Herald({ key: process.env.HERALD_SERVER_KEY });

await herald.track({
  user_id: 'user_42',
  event: 'trial_converted',
  properties: { mrr_cents: 4900 },
});

Verify

Open Settings → SDK → Live stream. Events arrive in real time. If nothing appears after 30 seconds:

• Check the browser console for CORS errors — add your hostnames under Settings → Hostnames.
• Confirm the key is pk_live_, not sk_live_. Public keys ship to browsers; server keys don’t.
• Disable aggressive content blockers on the test page. Herald routes through sdk.withherald.co, which most blockers leave alone — but a strict shield will eat the request.

Once events flow, Herald builds daily rollups immediately and the first briefing section lights up by Friday.