Install via npm

# Task: install FlowNavi in this app

FlowNavi shows in-app onboarding guides (product tours, checklists, tooltips, banners, surveys) inside a web app. Your job is to install its SDK in this codebase so that it loads for signed-in users, knows who the user is, and receives the data described below.

Reference articles. Everything you need is in this prompt; read the articles if you can and something is unclear:

- https://flownavi.com/help/sdk-and-installation/install-via-npm
- https://flownavi.com/help/sdk-and-installation/using-custom-data

API key: not included in this prompt. If the user gave you the key, use it. If they did not, ask them for it before you change any code. They find it on the Flows page of the dashboard (https://app.flownavi.com). It is a public key and is safe to ship in frontend code. In the code below, `YOUR_API_KEY` stands for it.

Work in this order: research (steps 1–4), then implement (step 5), then report (step 6). Do not write code before you have finished the research.

## How the SDK works

There are three calls. Do not use or invent any others.

1. **Load the SDK** with `FlowNavi.init` from the npm package.
2. **`identify(userId, properties)`** tells FlowNavi who the signed-in user is. No guide shows until it is called. Properties decide *who sees* a guide (for example "only admins on the Pro plan"). They are stored on FlowNavi's servers.
3. **`setVariables(variables)`** fills placeholders that guide authors type into guide text and URLs, such as `Welcome, {first_name}!` or `/workspaces/{workspace_id}/settings`. Variable values stay in the browser and are never sent to FlowNavi.

In this prompt, a **full page load** means the browser loading an HTML document from the server: the first visit, a reload, a new tab, or a link that causes a server round trip. Client-side navigation in a single-page app (a route change without a server round trip) is not a full page load.

Rules:

- The SDK runs in the browser only. Nothing may run during server-side rendering.
- Install it only in the part of the product that signed-in users use. Not on a marketing site, not on sign-in or sign-up pages.
- Load the SDK and call `identify` once after every full page load on which a user is signed in, not only right after they sign in. The SDK keeps the user in memory only, so a full page load starts from nothing.
- Do not call `identify` again on client-side navigation. The SDK detects route changes itself and needs no code for them.
- Call `setVariables` before `identify`, so the first guide that appears is already filled in.
- There is no logout or reset call. Do nothing on sign-out. If a different user signs in without a full page load, call `setVariables` and `identify` again for them.
- Calls made before the SDK has finished loading are queued, so you never need to wait for it.

## Step 1: Find where it goes

Find out and write down:

- Which app in this repository is the product that signed-in users use (there may be several apps or packages).
- How the frontend is built: a bundler with a `package.json` (npm, yarn, pnpm, bun), or server-rendered templates or plain HTML without a JavaScript build.
- Whether navigation between pages is client-side, a full page load, or a mix. This decides where the code must live so that it runs once after every full page load.
- Where the signed-in user becomes known in the browser: the auth provider, session hook, user store, root layout, or a server template that has the current user.
- Whether other third-party tools are already installed (analytics, error tracking, support chat, feature flags), for example calls like `identify`, `setUser`, or `boot`. Where they load and where they identify the user is where FlowNavi belongs. Their user data is also a good hint for steps 3 and 4.
- How the app tells production from other environments (environment variables, a config file, a build flag).
- Whether the app sends a Content-Security-Policy header or meta tag.

## Step 2: Install the npm package

The user has chosen the npm package. If this project has no `package.json` or no bundler, stop and tell the user: the alternative is the script tag, described at https://flownavi.com/help/sdk-and-installation/install-via-script-tag.

Do not install through a tag manager (Google Tag Manager, Segment, and similar), even if other tools are loaded that way. `identify` needs data from the app's own code.

Install `@flownavi/sdk` with the package manager this project already uses.

```js
import { FlowNavi } from "@flownavi/sdk";

FlowNavi.init({ apiKey: "YOUR_API_KEY", debug: false });
FlowNavi.setVariables({ ... });
FlowNavi.identify("USER_ID", { ... });
```

- `init` uses `window`. Call it only in the browser: in a client component, an effect, a client-only plugin, or behind a `typeof window !== "undefined"` check. Importing the package on the server is safe; calling `init` there is not.
- Call `init` before `setVariables` and `identify`. Calling it a second time does nothing.
- The package ships its own TypeScript types.

### Non-production environments

Outside production, turn on debug mode so test activity stays out of the analytics. Guides behave the same.

- npm: `FlowNavi.init({ apiKey, debug: true })`

Use the mechanism the app already has for telling environments apart. If you cannot find one, leave debug off and say so in your report.

## Step 3: Choose the user ID and the properties

**User ID**: the stable internal ID this app uses for the signed-in user. Never use an email address or a username.

- Pass it as a string or a number, in the form the app already has it. FlowNavi treats the number `8421` and the string `"8421"` as the same user.
- Always pass the same ID for the same user. If this codebase already sends this user's ID to FlowNavi from somewhere else (for example from the backend), use exactly that ID.
- The same applies to `company.id` below.

**Properties**: look at the user, account and subscription data the frontend already has, and pick the attributes a product team would use to decide who should see an onboarding guide. Typical ones:

- User: role or permission level, department, sign-up date, locale, usage counts (for example number of projects created).
- Company (the organisation, workspace, team or tenant the user belongs to, if the app has that concept): its ID, plan, trial status, seat count, creation date, industry.

Rules:

- Send each fact once, where it belongs. A plan or subscription usually belongs to the company; put it on the user only if this app bills individual users.
- Do not send personal data as properties: no email, name, phone number, address or free text the user typed.
- Allowed values: strings, numbers, and dates as ISO strings (`"2026-01-15"` or `"2026-01-15T10:00:00Z"`). Convert `Date` objects to ISO strings and booleans to `"true"` / `"false"`. Leave out arrays, objects, and values that are null or undefined.
- Name each property the way this app already names the field. Names are hard to change later, because guides will refer to them.
- Pick 3 to 8 properties that are clearly useful. Do not send everything.
- Company properties go in a nested `company` object. `company.id` is required whenever `company` is present and must be a non-empty string or a number. If the app has no such concept, leave `company` out.
- Use only data the frontend already has. If a useful value would need a new API field, do not build that; list it in your report.

```js
FlowNavi.identify("8421", {
  role: "admin",
  department: "sales",
  signedUpAt: "2026-01-15",
  company: { id: "312", plan: "pro", seatCount: 25 }
});
```

Call `identify` again, with the full set of properties, when one of them changes while the app is open (for example after an upgrade).

## Step 4: Choose the variables

Pick the values a guide author would want to show in text or use in a link:

- For text: first name, company or workspace name, plan name.
- For links: read the app's routes and find the dynamic parts of URLs that signed-in users visit, such as `/workspaces/:workspaceId/...` or `/org/:slug/...`. Each of those is a variable, so a guide can link to the user's own page.

Rules:

- Names may contain only letters, digits and underscores, for example `first_name` or `workspace_id`.
- Values must be strings or numbers. Passing `null` or `undefined` for a value is safe; that variable is then left unset.
- Personal data such as a name is fine here, because variable values stay in the browser.
- When a value changes while the app is open (for example the user switches workspace), call `setVariables` again with only the changed value: `FlowNavi.setVariables({ workspace_id: "57" })`. Guides on screen update at once.

## Step 5: Implement

- Put the code where step 1 pointed: next to the existing third-party tools if there are any, otherwise at the place where the signed-in user becomes known.
- Keep it in one place, for example one small module or component. Do not scatter calls through the codebase.
- Follow this codebase's conventions for file location, naming, config and environment variables. If other public keys live in environment variables, put the API key there too; otherwise write it inline.
- Do not call `identify` when no user is signed in.
- If the app sends a Content-Security-Policy, allow `https://sdk.flownavi.com` in `script-src` and `connect-src`.
- Run the project's type check, linter and build, and fix what you broke.
- Do not add tests, wrappers or abstractions that the codebase does not already use for comparable tools.

## Step 6: Report

Finish with a short report:

1. Where the SDK is loaded and where `identify` is called.
2. Files you changed.
3. The user ID field, plus a table of every property and variable: its name, where the value comes from, and an example value.
4. Anything you decided not to send, and anything useful you could not send because the frontend does not have it.
5. Anything you were unsure about.
6. What the user does next: deploy, open the app and sign in, then open the Flows page at https://app.flownavi.com and click **Test installation**.