Getting started

Quickstart

Install the package, initialise it with your key, and mount it. Five minutes to a working launcher, a little longer to a walkthrough that anchors to your UI.

Install

bash

npm install nudge-sdk

The package is self-contained. There is nothing else to load, no script tag, no CDN. It ships its UI and its transport in one bundle.

Initialise and mount

Call init() once, early in your client code, then mount(). It has to run in the browser, so if you use server-side rendering, guard it.

app entry

import { NudgeSDK } from "nudge-sdk";

const nudge = NudgeSDK.init({
  apiKey: "pk_live_…",                 // your publishable key
  apiBase: "https://your-backend.com/api",
  defaultProjectKey: "demo-counter",   // flow the launcher starts on click
});

nudge.mount();

React

Run it in a client-only effect so it never executes during SSR, and guard against double mounting on hot reload.

tsx

useEffect(() => {
  const nudge = NudgeSDK.init({
    apiKey: "pk_live_…",
    apiBase: "https://your-backend.com/api",
    defaultProjectKey: "demo-counter",
  });
  nudge.mount();
  return () => nudge.destroy();
}, []);

Getting apiBase right

The SDK builds request URLs by appending /sdk/sessions, /sdk/match, and so on to apiBase. Your backend mounts those routes under /api/sdk/*, so apiBase is everything up to but not including /sdk.

Backend at https://api.example.com means apiBase: "https://api.example.com/api"
Local dev means apiBase: "http://localhost:3001/api"

What you see

After mount()a floating launcher appears in the bottom-right corner. By default it reads "Ask your buddy". Clicking it does one of two things:

If you set defaultProjectKey, it starts that flow straight away.
If you did not, it opens a text box where the user types what they want to do, and the backend matches or generates a walkthrough for that goal.

Allow your origin

The browser will block the SDK's requests unless your site's origin is allowed by the backend. For a distributed SDK you do not hand-list every customer domain. Instead the SDK routes accept any origin at the CORS layer, and each publishable key carries its own origin allowlist that you control. See Troubleshooting if you hit a CORS error or a blank 500 on the preflight.

Make the steps anchor

A walkthrough can only point at an element that exists on the page. Add a stable attribute to the elements your flow targets:

html

<button data-nudge-id="save">Save</button>
<a data-nudge-id="resume-link" href="/resume">Résumé</a>

Now a step whose selector is [data-nudge-id="save"] finds the button and draws the cursor on it. Without a stable attribute the step still shows its text, but it has nothing to point at.

PreviousIntroduction NextConfiguration