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

Yes. Users must sign in again after upgrading. Partner integrations that manage Narrative user accounts or branding also need an update. See the v1.9.0 release notes for guidance.
Yes. In Settings, open Privacy & Security and Active sessions. End session ends one other session; End all other sessions keeps only the current one. Normal logout ends the current session without ending other independent sessions. An ended session must sign in again to access the workspace.
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. Xero was introduced in v1.5.14. In v1.8.7, provisioned users manage it alongside QuickBooks Online in Settings under Accounting connections, including organisation selection, readiness, the last complete update, refresh, reconnect and disconnect. Available product use depends on the supported source and enabled experience.
No. Direct point-of-sale connections are not supported. Owners can use the supported bank and accounting connections for available financial data; Coach does not promise a POS integration or a delivery date.
Short explanations show how the answers help tailor suggestions and market context. Users can select relevant choices, type their own answers, ask for clarification and skip optional business context. The bank connection is read-only and cannot move money.
Yes. Skipping the optional description keeps the saved website. If both website and description are skipped, Coach can still help with finances and explains where to add background later for tailored Growth ideas.
Select Tell Coach about your business from Growth or the first Coach visit. The dedicated Business background conversation accepts a description or website and confirms what was saved. It respects the existing public-information setting, and Skip for now leaves the profile unchanged. See the Growth guide.
Not necessarily. After onboarding processing has succeeded, a save that makes the required inputs ready can start preparation. Growth shows the actual progress or failure and offers Try again when available. Saving background does not enable public information or guarantee immediate ideas.
It is available on the first-visit day until the owner sends a Coach message. Adding background in the dedicated Business background conversation preserves the offer. Selecting the starter or sending from the empty composer gives a short capability answer. On subsequent days, Coach uses the daily briefing.
No. Suggestions aim for two useful next questions, with fewer when a truthful continuation is unavailable. They wrap on narrow screens. The first-use capability answer keeps its saved starters after reload; ordinary generated suggestions can change.
No. Conversion cards identify ECB reference data or a rate derived from it, with the date and source. A usable retained rate is identified when the latest update is unavailable. Rates older than seven calendar days are not used for conversions, including in saved cards.
Not solely because of this release. A connection lacking the payment-read permissions it needs must reconnect and approve the requested access; equivalent existing permissions may already cover it. Follow the connection’s recovery guidance.
In v1.8.8, the SDK can request up to 749 days where the provider and consent permit it. Actual coverage depends on the bank and account, and banks with shorter history allowances can still be connected. Existing connections are not automatically backfilled; extending history can require reconnecting and renewing consent.
Yes. In v1.8.8, Action details include thumbs-up and thumbs-down controls with an optional note. Submit saves feedback, Cancel leaves saved feedback unchanged, and a saved rating can be edited. Ratings belong to the content reviewed and do not dismiss an Action, change its priority or start a Project.
In v1.8.9, View all and Show less change the visible row count while retaining consistent counterparty names and categories. Saved Money details remain readable, and expanded receipts use current records for the originating reporting period.
Yes. In v1.8.9, Ask Coach from Money in retains the selected dates, receipt totals and comparison in relevant follow-ups, including after reopening the conversation.
In Transactions, choose the period and select a populated category to expand its records. Select it again to collapse the list. Coach Help can explain the steps and how Narrative groups transactions from bank information.
No. Business Profile requires a nonblank company name, shows a field error for an invalid draft and preserves the saved profile when that edit is rejected.
Company names can include letters from different languages and common business punctuation, including ampersands, apostrophes, full stops, hyphens and parentheses. Use plain text, do not leave the name blank, and keep it within 160 characters. The same rules apply during registration and Business Profile edits.
Yes. In v1.9.0, the reminder’s Email subject and Email text fields can be edited before Copy text copies the displayed subject and body. Edits stay on the open page only; reopening the conversation restores the original draft.
No. Preparing, editing and copying send no email and contact no customer. The draft has no recipient-address field. The owner reviews the wording and pastes it into their own email application.
In v1.8.8, Coach shows the current step, elapsed time and an expandable list of completed and in-progress work. The steps reflect the question and the work being carried out. A greeting shows only its relevant steps.
When the failed work can be retried, setup keeps the user’s answers and offers Retry setup. Other failures show support guidance. A retry option is not a guarantee that every setup failure can be recovered automatically.
No. It opens an ordinary conversation tied to the selected Action. An existing Money Project can open its own separate Coach conversation.
The original finding, submitted background under Your Context, and saved Execution plan remain available. An applicable change explanation appears under Why this approach. Opening the Project does not generate a new plan, and cancelled or archived Projects retain read-only history.
Yes. In v1.8.7, relevant stable business context shared by the user can inform later conversations. Users can correct that context or ask Coach to forget it. Remembered background does not replace current financial records.
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.
Yes. In v1.8.4, Settings accepts custom sector text, consistent with onboarding. Existing custom sector values are preserved.
Yes. Saved task text and completion state persist across refresh and a fresh sign-in.
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.
In v1.8.5, users can select Help from the Coach menu. The composer shows a visible @help marker, and Coach answers from maintained guidance for the deployed product version while keeping the exchange in normal conversation history.
Yes. In v1.8.5, Coach can honour explicit periods across the available transaction history and can produce longer cash-planning scenarios when enough evidence is available. It states coverage limits, keeps observed and projected values separate, and labels longer forecasts as assumption-based estimates.
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 in Coach with a goal-aware introduction and up to three available Money and Growth cards. When there are no cards, Coach explains the appropriate next step. What can you do? appears before the first Coach message. See the first-visit guidance.
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. In v1.8.8, an explicit referral opt-out in the tenant’s existing configuration is respected across Coach, Money, Growth and Projects. It is managed by Narrative and the partner team, not through the end-user branding controls.
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.