Getting started

Quickstart

The whole integration is three steps: install the package, turn it on with your key, and tag the buttons you want walkthroughs to point at. Ten minutes, start to finish.

Before you start, have these two things

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.
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

bash

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).

app entry

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.

Using React / Next.js?

Run it inside an effect so it never executes during server-side rendering:

tsx

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

That’s it — there is no step 3

Nudge reads the page your user is actually looking at. When someone asks a question, the SDK describes what is currently on screen — roles, labels, and the section each control sits in — and resolves their question against that. It does not need a recorded flow, a tagged DOM, or a build plugin to point at your Save button.

Note

Optional: pin the elements you care most about. Adding data-nudge-id to a handful of important controls makes them unambiguous, which helps when a screen has several controls with the same label. It is an improvement, not a requirement — skip it entirely and everything still works.

html

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

Recording flows is optional in the same way. A recorded flow is the fastest and most predictable answer to a question you already know your users ask, so it is worth recording your top handful — but nothing breaks if you never record one.

Step 4 — Try it end to end

Open your app in the browser.
Click the launcher and type a task your app supports.
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.

PreviousIntroduction NextConfiguration