Quickstart

Before you start, have these two things

1. Your publishable key — it starts with pk_live_ and comes from your dashboard. It is safe to put in frontend code; that is what it is for.
2. Your API base URL — where your Nudge backend runs, plus /api. For example https://api.example.com/api, or http://localhost:3001/api in local dev.

Step 1 — Install

npm install nudge-sdk

That is the only thing to install. No script tag, no CDN, nothing else to load — the package carries its own UI.

Step 2 — Turn it on

Call init() once when your app starts, then mount(). This must run in the browser (not on the server).

import { NudgeSDK } from "nudge-sdk";

const nudge = NudgeSDK.init({
  apiKey: "pk_live_…",                     // 1. your publishable key
  apiBase: "https://your-backend.com/api", // 2. your API base URL
});

nudge.mount();

Reload your app. A floating "Ask your buddy" button now sits in the bottom-right corner. Click it, type what you want to do, and Nudge finds or generates a walkthrough for it. That is the integration working.

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

Step 3 — Tag your elements with data-nudge-id

This is the one thing that makes walkthroughs actually point at your UI. Add a data-nudge-id attribute to each button, link, or field a walkthrough should be able to highlight. Pick short names that describe what the element does:

<button data-nudge-id="save">Save</button>
<button data-nudge-id="new-invoice">New invoice</button>
<input  data-nudge-id="search" placeholder="Search…" />

A step that targets save now finds your Save button and draws the cursor on it — and keeps finding it even when you redesign the page, because the id does not change when classes and layout do. Without a tag, a step can still show its instruction text, but it has nothing to point at.

You do not need to tag everything on day one. Tag the handful of elements your first walkthrough uses, ship it, and add more as you author more flows.

Step 4 — Try it end to end

1. Open your app in the browser.
2. Click the launcher and type a task your app supports.
3. Watch the cursor and instruction card walk through the tagged elements.

If requests fail, the usual cause is the origin allowlist: your publishable key carries a list of website origins it may be used from (you manage it in the dashboard — no backend change needed). A blank or CORS-looking error usually means your site's origin is not on the key's list yet. Troubleshooting walks through the rest.

Make it better (each one optional)

The three steps above are a complete integration. When you want more:

• Start a specific flow from the button. Pass defaultProjectKey: "onboarding" to init() and the launcher starts that flow directly instead of asking the user to type.
• Match your brand. Colors, position, and text of everything Nudge draws — Customising the UI.
• Recognise returning users. Pass endUserIdHash (a hash of your user id, never the raw id) so progress and analytics stick per user — Configuration.
• Record flows by clicking through them. Enable authoring for your admin users and capture walkthroughs inside the app — Dev mode & authoring.
• Let Nudge generate walkthroughs it was never taught. Build a vocabulary of your app so the backend can write new flows on demand — Vocabulary.