Set up the coach with code
Install @rydhm/web, sign your users, give the coach your app’s context and tools, and keep guides and the page map in your repository.
This page is for developers. The no-code set-up and this one can be mixed: a script tag with a few calls, or the npm package with everything in code.
Install
Rydhm.init makes one cheap request (the bubble, guides and announcements due for this user) and no voice connection. Voice starts only when the person clicks the bubble, or when you call await rydhm.start() from a click. livekit-client is loaded with a dynamic import(), so visitors who never talk to the coach never download it.
Early access. Workspaces on staging.rydhm.ai pass apiUrl: "https://api-staging.rydhm.ai" to Rydhm.init.
Signed users
By default the user id you pass is stored as anonymous (anon_<id>): anyone could claim it, so it can never read a signed user’s progress. To prove who the user is, your server signs the id with the workspace’s user-signing secret, and the page passes the id with its hash. Turn on Only signed-in users on the website key (the coach’s Settings → Website keys; requireSignedUser: true in the API) to refuse everyone else.
The secret belongs to the workspace: an admin creates it in the coach’s Settings → Signed-in users → Create secret (or Rotate secret). It’s shown once, so store it with your server’s other secrets as RYDHM_ENGINE_USER_SECRET. The hash is hex(HMAC-SHA256(secret, userId)), the same scheme as Intercom’s identity verification:
Node (@rydhm/sdk)
Python (rydhm)
Any language
Then in the page:
Never compute the hash in the browser, and never send the secret there. signUserId refuses ids the Engine would refuse: empty, longer than 200 characters, with spaces around them or control characters, or starting with anon_. traits (up to 4 KB) are what audiences match on.
Tell the coach what’s going on
The coach already knows the page’s address and title; you don’t need to send them. Page addresses are sent without their query string.
Give it your own tools
A tool is a function in your page that the coach can call: look something up, open a dialog, change a setting. Describe its arguments with JSON Schema:
Names are lowercase with underscores (2 to 41 characters), and a page can register up to 20. The handler’s signal aborts when the coach stops waiting. Throw an Error to tell the coach it failed: its message is what the coach hears. See Client tools for the full protocol.
Navigation with your router
The coach changes page with the built-in navigate tool. Give it your router so pages change the way a click would:
Next.js (App Router)
React Router
Script tag
Without a router, navigate: 'auto' (the default) uses history.pushState, and loads the page for real if nothing on the page changed within 700 ms. The coach can never navigate to another website.
Your own UI (headless)
With ui: 'none' nothing is drawn, and everything still works: the spotlight still highlights, and risky clicks still ask (your confirm, or the browser’s). Build your own button and captions from the events:
Every option, method, event and error code is in the Browser SDK reference.
Guides and the page map as code
Keep the page map and your guides in your repository and push them from CI with a secret key (scope experts:write), so they change with your UI.
TypeScript
Python
completeWhen takes value, or the browser SDK’s own name for it: pattern for a page, target for a click, name for an event or a tool. Announcements and publishable keys work the same way: rydhm.engine.announcements.create(expertId, { title, body, guideId }) and rydhm.engine.publishableKeys.create(expertId, { allowedOrigins }). See the TypeScript SDK and the API reference.
The examples/onboarding-coach-html (script tag, plus create-guide.mjs that creates a sample guide) and examples/onboarding-coach-nextjs (signed users through an API route, a custom tool, the App Router) folders that come with the SDKs run as they are.