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, synchronisation 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.
In the Narrative-managed email registration flow, new users must acknowledge the Terms of Service and Privacy Policy before registration can continue. Existing users are not asked to complete this registration step again when signing in.
Yes. In v1.5.12, users can connect multiple bank accounts when those accounts use the same currency. Additional accounts are added from Settings after the primary account has been connected.
Not in the current release. Multi-account support is limited to same-currency accounts. Different-currency account connections are rejected before account data is saved.
The SDK starts a data reload so Money, transaction views, and Coach can use the broader account set. Users see processing guidance and receive an email when the new account data is ready.
Yes. In v1.5.14, provisioned users can connect Xero, choose the relevant organisation, and synchronise accounting data such as accounts, contacts, invoices and bills, bank transactions, profit and loss records, and balance sheets. Enabled product surfaces can use that accounting context once the connection is available for the tenant and synchronisation has completed.
New users must provide business name, first name, and last name before continuing into onboarding. Existing users with stored identity data are not asked to re-enter it.
Your journey is the progress experience. It shows the user’s current phase, completed milestones, next action hints, and follow-through progress across Money, Growth, and Coach.
Distinct Money action review and follow-through can advance journey progress. In the first journey phase, users review three Money actions, set a goal with Coach, and choose at least two priorities.
Yes. In v1.5.13, Coach can answer a first set of QuickBooks accounting questions when connected accounting data is available, including overdue invoices, customer balances, vendor bills, top vendors, and accounting expense categories.
In v1.8, selecting New can keep the current Daily Briefing visible above the clean conversation state. No empty chat session is created until the user sends a message or chooses an action that needs one.
Money recommendations use a richer presentation path with clearer situation, consequence, practical actions, caveat, and supporting evidence. Targeted follow-up answers can stay attached to the relevant recommendation so the displayed result remains consistent after refresh or regeneration.
Growth opportunities carry stronger commercial context, and generated Projects start as drafts with clearer scope, current focus, progress, and schedule activation before dated execution begins.
Coach Actions can appear in the action menu, but unavailable actions remain disabled and cannot be launched. Report or action availability depends on the tenant’s enabled product experience.
The first visit opens as a Coach-led welcome and goal bridge. Quick-win cards can still take users into the relevant Money action details.
Money actions are designed to focus on one specific opportunity, name the relevant counterparty or category where available, show an estimated impact when supported, and include source or comparison context where it helps the user decide what to do next.
Yes. In v1.5.9, Money can ask targeted follow-up questions when transaction data alone cannot confirm eligibility or usage. The item is then resolved into a confirmed recommendation or dismissed with context.
Report delivery depends on the enabled Coach Action. When a report action is not enabled for the tenant, the product shows it as unavailable rather than starting the workflow.
In v1.5.14, competitor intelligence favours nearby competitors more directly, uses fallback discovery when local sources return no useful places, and avoids advice that conflicts with constraints the owner has already stated.
Yes. In v1.5.8, Money insights can be snoozed when they are relevant but not actionable today. Snoozed items are retained across refresh cycles and can be managed from a dedicated view.
The initial Money load uses backend latest selection so newly onboarded users can see fresh metrics as soon as they are available. Explicit dated contexts should still be preserved when the user intentionally arrives from a dated flow.
Yes. Research into grants, tax reliefs, public finance programmes, training support, and similar SME support opportunities can feed relevant matches into Money as scheme-type insights when enough business context is available.

​
Partner customisation

Yes. Tenant experiences can be white-labelled with partner colours, selected typography, email presentation, and partner-specific visual treatment.
Yes. v1.5.7 supports partner-specific coaching personality configuration so the assistant can better match a tenant’s preferred tone and vocabulary.
Approved remote custom font URLs are supported for tenant themes. Uploaded font files are not supported in this release.

​
Getting help

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