What you need first
- 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. - 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. Addhttp://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
Initialize
Initialize once at app startup, and keep the returned client so you can callidentify later.
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:
Configuration
Every option exceptapiKey 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, callidentify 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 withdebug: 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.