> ## Documentation Index
> Fetch the complete documentation index at: https://docs.narrativebanking.com/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ

> Frequently asked questions about Narrative SDK integration.

Use this page for the most common integration questions before or during implementation. If you are already debugging a failure, start with [Troubleshooting](/sdk/troubleshooting).

## Integration basics

<AccordionGroup>
  <Accordion title="Do I need to install an npm package?">
    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.
  </Accordion>

  <Accordion title="Which frameworks are supported?">
    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.
  </Accordion>

  <Accordion title="Can I embed multiple widgets on one page?">
    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.
  </Accordion>

  <Accordion title="What browsers are supported?">
    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.
  </Accordion>
</AccordionGroup>

## Authentication

<AccordionGroup>
  <Accordion title="How long should the Embed Token live?">
    Keep it short-lived. Current guidance is typically 5–15 minutes, with `iat` and `exp` expressed in Unix seconds.
  </Accordion>

  <Accordion title="Should I store the Embed Token in the browser?">
    No. Treat it as a short-lived bootstrap credential. Do not store it in local storage or other long-lived browser persistence.
  </Accordion>

  <Accordion title="What happens when the Embed Token expires?">
    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.
  </Accordion>

  <Accordion title="What makes a token valid?">
    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.
  </Accordion>

  <Accordion title="When should the frontend fetch the Embed Token?">
    Fetch it only after the tenant application has already established its own authenticated user session and shortly before mount or boot time.
  </Accordion>
</AccordionGroup>

## Embedding runtime

<AccordionGroup>
  <Accordion title="Should I use declarative or imperative boot?">
    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.
  </Accordion>

  <Accordion title="How does the SDK handle SPA route changes?">
    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.
  </Accordion>

  <Accordion title="Do I need to call NSDK('destroy') on unmount?">
    Yes when you use imperative mode and your SPA unmounts or replaces the widget container. This helps prevent stale runtime state between navigations.
  </Accordion>

  <Accordion title="Can I delay boot until the page is fully ready?">
    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', ...)`.
  </Accordion>
</AccordionGroup>

## Security

<AccordionGroup>
  <Accordion title="Can I sign tokens in the frontend?">
    No. Keep the Connected App secret and all token-signing logic on your backend only.
  </Accordion>

  <Accordion title="What CSP headers do I need?">
    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.
  </Accordion>

  <Accordion title="Is the Embed Token visible to end users?">
    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.
  </Accordion>

  <Accordion title="Can I include extra metadata in the token?">
    Yes, but keep it small and non-sensitive. Use optional metadata only for values the embedded experience actually needs at runtime.
  </Accordion>
</AccordionGroup>

## API & data

<AccordionGroup>
  <Accordion title="How do I know if my integration is working?">
    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.
  </Accordion>

  <Accordion title="What does a 401 after successful embed mean?">
    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.
  </Accordion>

  <Accordion title="How often does data refresh?">
    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.
  </Accordion>

  <Accordion title="Can I test with mock tenant users first?">
    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.
  </Accordion>

  <Accordion title="Can users connect more than one bank account?">
    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.
  </Accordion>

  <Accordion title="Can users connect bank accounts in different currencies?">
    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.
  </Accordion>

  <Accordion title="What happens after a user connects another bank account?">
    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.
  </Accordion>

  <Accordion title="What identity data is required before onboarding?">
    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.
  </Accordion>

  <Accordion title="What is Your journey?">
    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.
  </Accordion>

  <Accordion title="How do Money actions affect journey progress?">
    Distinct Money action responses can advance journey progress. Repeating the same card interaction does not count as multiple progress events, and bookmarked actions can later be marked done when the user follows through.
  </Accordion>

  <Accordion title="What changed in the first visit for v1.5.10?">
    The first visit now focuses on a short welcome, the user's stated goal, and two or three personalised Money quick-win cards so users can review useful actions soon after setup completes.
  </Accordion>

  <Accordion title="How are Money recommendations grounded?">
    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 for research-enriched actions.
  </Accordion>

  <Accordion title="Can Money ask follow-up questions before showing a recommendation?">
    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.
  </Accordion>

  <Accordion title="How are curated reports delivered?">
    Financial reports and competitor or market intelligence reports are requested from the product experience and delivered by email after preparation.
  </Accordion>

  <Accordion title="Can users snooze insights instead of dismissing them?">
    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.
  </Accordion>

  <Accordion title="Why does Money use the latest available snapshot on first load?">
    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.
  </Accordion>

  <Accordion title="Can the SDK surface grants or tax-benefit opportunities?">
    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.
  </Accordion>
</AccordionGroup>

## Partner customisation

<AccordionGroup>
  <Accordion title="Can the SDK use partner branding?">
    Yes. Tenant experiences can be white-labelled with partner colours, selected typography, email presentation, and partner-specific visual treatment.
  </Accordion>

  <Accordion title="Can the Coach tone match a partner brand?">
    Yes. `v1.5.7` supports partner-specific coaching personality configuration so the assistant can better match a tenant's preferred tone and vocabulary.
  </Accordion>

  <Accordion title="Can partners use custom fonts?">
    Approved remote custom font URLs are supported for tenant themes. Uploaded font files are not supported in this release.
  </Accordion>
</AccordionGroup>

## Getting help

<Info>
  If you are debugging a concrete failure, use [Troubleshooting](/sdk/troubleshooting). If you still need help after self-service checks, use [Support](/sdk/support).
</Info>