Configuration

NudgeSDK.init({
  apiKey: "pk_live_…",          // required
  apiBase: "https://…/api",     // required
  defaultProjectKey: "demo",    // launcher starts this flow on click
  trigger: { mode: "button" },  // "button" (default) or "programmatic"
  theme: { /* see Customising the UI */ },
  endUserIdHash: "u_3f9c…",     // stable, hashed user id (never raw PII)
  onEvent: (e) => console.log(e.type),
  authoring: { enabled: false, aiAssist: true },
  privacy: { redactSelectors: [], replaceDefaults: false },
});

Required

apiKey

Your publishable key, the one that starts with pk_. It is safe to ship in client code. It maps to a tenant and can carry an origin allowlist that you set when you create the key. Secret keys (sk_) are server-only and must never appear in the browser.

apiBase

The base URL of your backend, up to but not including /sdk. The SDK appends the route paths itself. See the Quickstart for the exact value.

Behaviour

defaultProjectKey

The flow the launcher starts when the user clicks it. Leave it out and the click opens a goal input instead, which routes through match and then generation.

trigger

{ mode: "button" } shows the floating launcher (the default). { mode: "programmatic" } renders no launcher, so you start walkthroughs yourself by calling the controller methods. Use programmatic mode when you want your own button or a menu item to trigger Nudge.

Identity

endUserIdHash

A stable, hashed identifier for the current user. Pass a hash, never raw email or a real id. It lets the backend keep per-user history (which walkthroughs someone has seen or finished) without ever holding personal data.

Events

onEvent

A single callback that fires for every lifecycle event. Use it for analytics or to react in your own UI. The types you will see most:

• session_started, session_completed
• step_started, step_completed, wrong_click
• goal_matched, goal_unmatched, goal_generated
• authoring_started, step_recorded (when recording)

onEvent: (e) => {
  if (e.type === "session_completed") analytics.track("nudge_done", e);
  if (e.type === "wrong_click") analytics.track("nudge_misclick", e);
}

Authoring

Turning on authoring shows a record button for privileged users so they can capture a walkthrough by clicking through the app. The key must carry the authoring capability or the publish call is rejected. Covered in full on Dev mode and capture.

authoring: { enabled: true, aiAssist: true }

• enabled shows the record button.
• aiAssist (on by default) asks the backend to write the instructions and the flow title after you stop recording. Set it to false to keep the captured content exactly as recorded.

Privacy

The recorder never captures password or credit-card inputs, and never captures anything marked data-nudge-skip. Those protections are on by default. You can add more:

privacy: {
  redactSelectors: [".ssn", "[name='dob']"],
  replaceDefaults: false,   // keep the built-in protections; just add yours
}