Skip to main content
Use this page for the most common integration questions before or during implementation. If you are already debugging a failure, start with Troubleshooting.

​
Integration basics

Not for the standard hosted integration path described in these docs. Load the SDK through nsdk-loader.js, render a host container, and provide a short-lived Embed Token from your backend.
The hosted SDK approach works with any frontend stack that can load a script, render a DOM container, and fetch a backend token route. React, Vue, Angular, and server-rendered applications can all support this pattern.
The standard documented integration path uses a single container and single mount target. If you need multiple widgets on one page, confirm the supported pattern and runtime constraints with Narrative before implementation.
Use a modern evergreen browser with standard support for secure iframes, HTTPS, and current JavaScript features. If you support older enterprise browsers, validate your exact host environment before launch.

​
Authentication

Keep it short-lived. Current guidance is typically 5–15 minutes, with iat and exp expressed in Unix seconds.
No. Treat it as a short-lived bootstrap credential. Do not store it in local storage or other long-lived browser persistence.
It can no longer be used to start a new embedded session. If the user needs to boot the SDK again, fetch a fresh token from your backend.
It must be an HS256 JWT with aud = nsdk-embed and the required claims: iss, sub, aud, iat, exp, and jti. Include nsdk.user.name and nsdk.user.email so the session has the expected user context.
Fetch it only after the tenant application has already established its own authenticated user session and shortly before mount or boot time.

​
Embedding runtime

Use declarative boot when you have a stable host page and container. Use imperative boot when your application needs explicit control over mount timing, route transitions, or cleanup.
Your application should treat route changes as part of the host lifecycle. If the mount container is removed or recreated, re-run the boot flow and clean up prior runtime state when needed.
Yes when you use imperative mode and your SPA unmounts or replaces the widget container. This helps prevent stale runtime state between navigations.
Yes. That is a common reason to choose imperative mode. Make sure the container exists, the user session is ready, and the Embed Token is fresh before calling NSDK('boot', ...).

​
Security

No. Keep the Connected App secret and all token-signing logic on your backend only.
At minimum, your host application must allow the SDK origin for the hosted loader script and embedded frame. Review script-src, frame-src, and any related network policies used by your environment.
It may be observable in the browser during normal page operation, which is why it must be short-lived, minimally scoped, and never contain secrets.
Yes, but keep it small and non-sensitive. Use optional metadata only for values the embedded experience actually needs at runtime.

​
API & data

Start with the basic path: the loader script loads, the token route returns a fresh token, the widget renders, and protected downstream requests succeed after boot.
It usually means bootstrap succeeded but the downstream request is still missing the expected user, tenant, or product-surface access state. Check the exact API or experience you are trying to reach next.
Data freshness depends on the upstream data source, synchronization timing, and the provisioned experience. If expected data is missing, verify environment, tenant-user mapping, and sync completion before assuming an auth problem.
Yes. That is often the fastest way to validate token minting, host-page boot logic, and environment wiring before moving to broader tenant-user coverage.

​
Getting help

If you are debugging a concrete failure, use Troubleshooting. If you still need help after self-service checks, use Support.