Skip to main content
Hinto needs session evidence from your web app. This guide covers the manual install path. If you use a coding agent, Hinto’s onboarding hands you a short prompt that links the Hinto Signal guide. The agent follows that guide, pairs with Hinto for the keys, and adds your websites itself. You approve its pairing code.

What you need first

  1. The publishable key of your organization’s Signal app, from Hinto under Settings > Hinto Signal. If there is no app yet, choose Set up without a coding agent there. Every website and mobile app of your organization uses this same key. It can only send session data and open support. It cannot read tickets, customers, or investigations, and it is safe to ship in your frontend bundle. Never put a secret key (hinto_sk_…) in a website.
  2. Your website on the list in Settings > Hinto Signal: under Products, choose Add website and enter its exact origin, such as https://app.example.com. The browser blocks requests from a website that is not on the list before they ever reach Hinto. Add http://localhost:3000 (or whichever port you use) while you develop. A coding agent that pairs with Hinto adds the origins it sends, so this step is only for the manual path.

Install

Use whichever package manager the project already uses.

Initialize

Initialize once at app startup, and keep the returned client so you can call identify later.
The SDK sends to https://api.gethinto.com. Pass apiUrl only when you point it at a different Hinto deployment. Pass your publishable key as apiKey. Put it in an environment file rather than hard-coding it. It ends up in your frontend bundle either way, which is fine for a publishable key, but an env var is what lets you roll it without a code change. Call initHinto once per page. A second call stops the first client. Without a bundler, load the script build from a CDN. It defines a global Hinto:
The script build has session capture and journeys. The support conversation needs the npm package.

Configuration

Every option except apiKey is optional. Script errors and unhandled promise rejections are always recorded, with their message and stack.

Client methods

When Hinto cannot be reached, the SDK keeps up to 500 events and retries after 5 seconds, doubling the wait up to 5 minutes.

Identify your users

After sign-in, call identify so sessions attach to a customer. See Identify users for email vs external id and why it matters. To report journeys, capture needs the signed-in customer’s external_id: pass initialIdentity: { kind: "external_id", value: user.id } to initHinto for the signed-in user, or call identify with that identity after sign-in. A journey belongs to that customer, so it lasts through reloads and redirects in the same tab, and it can attach to their support conversation. Hinto Signal support also needs the external_id identity, with the same id your server puts in the support token’s sub. The conversation reads the user’s name, email, and company from that signed token, not from identify. Once support runs, do not call identify with an email or another kind of identity: the conversation checks the external_id, and its sends fail.

Verify it works

Run your app with debug: true, sign in, and load a page. The console shows [Hinto] ingest response: accepted N, duplicates N, rejected N warnings. rejected 0 means Hinto took every event. Remove debug: true afterwards. The next ticket from that customer cites the session.