# Vue quickstart

Add a Web Agent to a Vue 3 single-page app. At the end, the agent's launcher is on every page of your app and the agent knows which user is signed in.

## Prerequisites

- A Vue 3 app built with Vite, written with `<script setup>`.
- A Web Agent in your workspace whose analysis has finished, with a version deployed to Production.

## 1. Copy your agent ID

1. In the portal, go to [**Web Agents**](https://auth.faustine.ai/go?to=%2Fweb-assistants) and select your agent.
2. In the **Overview** tab, find the **Install the assistant** card and select the **npm** tab.
3. Copy the `agentId` value from the snippet.

## 2. Install the loader

**npm**

```bash
npm install @faustine-ai/web-agent
```

**pnpm**

```bash
pnpm add @faustine-ai/web-agent
```

**yarn**

```bash
yarn add @faustine-ai/web-agent
```

**bun**

```bash
bun add @faustine-ai/web-agent
```

The package has no dependency on Vue. It loads the widget and your agent's served version from Faustine when the page loads.

## 3. Start the agent

Create a module that starts the agent, and import it from `src/main.ts`. The agent lives outside the Vue app, so it needs no plugin and no component.

```ts filename="src/faustine.ts"
import Faustine from '@faustine-ai/web-agent';

export const agent = Faustine.init({
  agentId: '<AGENT_ID>',
});
```

```ts filename="src/main.ts"
import { createApp } from 'vue';
import App from './App.vue';
import router from './router';
import './faustine';

createApp(App).use(router).mount('#app');
```

`init` loads the Production environment. To load another one, pass its name: `env: 'Staging'`.

## 4. Identify the signed-in user

Write a composable that watches the user and tells the agent when it changes. This example passes a display name and email, which appear in the agent's **Monitoring** tab as **Unverified**.

```ts filename="src/composables/useFaustineUser.ts"
import { watch, type Ref } from 'vue';
import { agent } from '../faustine';

type User = { id: string; name: string; email: string };

export function useFaustineUser(user: Ref<User | null>) {
  watch(
    user,
    (current, previous) => {
      if (current) {
        agent.identify({ userId: current.id, name: current.name, email: current.email });
      } else if (previous) {
        agent.logout();
      }
    },
    { immediate: true },
  );
}
```

`immediate: true` runs the watcher once at setup, so a user who is already signed in when the app loads is identified. `logout` runs only when the user goes from a value to `null`, so a visitor who never signs in keeps their conversation.

Call the composable from `App.vue`. `useSession` stands for your own composable or store, and `user` is a ref that holds the signed-in user or `null`.

```vue filename="src/App.vue"
<script setup lang="ts">
import { useSession } from './session';
import { useFaustineUser } from './composables/useFaustineUser';

const { user } = useSession();
useFaustineUser(user);
</script>

<template>
  <RouterView />
</template>
```

With Pinia, get the ref with `storeToRefs`: `const { user } = storeToRefs(useSessionStore())`.

For production, replace the labels with a token signed by your backend. See [Verify your users with a signed token](https://docs.faustine.ai/web-agents/verify-users/).

## 5. Run your app

```bash
npm run dev
```

> **Checkpoint:** The agent's launcher appears on the page. Select it and send a message. In the portal, the conversation appears under the agent's **Monitoring** tab.

## Install with a coding agent

The `install-faustine` skill does steps 2 to 4 in your repository and follows its conventions.

```bash
npx skills add faustine-ai/skills
```

Then, in your coding agent:

```text
/install-faustine <AGENT_ID>
```

## Install without a build step

If you cannot add a dependency, load the widget from a script tag in `index.html`. The **JS / Auto** tab of the **Install the assistant** card has this snippet with your ID filled in.

```html filename="index.html"
<script src="https://webagent.faustine.ai/embed?wid=<AGENT_ID>" async></script>
```

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| No launcher, and the request to `webagent.faustine.ai/embed` returns `404` | No environment of the agent serves a version. | [Publish a version](https://docs.faustine.ai/web-agents/publish-a-version/). |
| No launcher, and the same request returns `403` | The page's domain is not in the environment's allowed domains. | See [Restrict the domains that can load the agent](https://docs.faustine.ai/web-agents/restrict-domains/). |
| The user is not identified after sign-in | The composable received a plain object, not a ref, so the watcher never runs again. | Pass the ref itself, or a getter: `watch(() => store.user, …)`. |
| The server log shows `init called outside a browser` | The app renders on the server and `src/faustine.ts` ran there. `init` does nothing on the server. | No change is needed. The agent starts when the app loads in the browser. |

## Next steps

- [Verify your users with a signed token](https://docs.faustine.ai/web-agents/verify-users/): give users their history on every device.
- [Restrict the domains that can load the agent](https://docs.faustine.ai/web-agents/restrict-domains/): allow your own domains only.
- [Use your own launcher button](https://docs.faustine.ai/web-agents/custom-launcher/): open the agent from a button in your layout.
- [JavaScript API](https://docs.faustine.ai/reference/javascript-api/): every option of `init` and every method of the handle.