# Installation

Installation puts a Web Agent's widget on the pages of your app. You add a script tag or the `@faustine-ai/web-agent` package once. The widget and the agent's actions load from Faustine each time a page loads.

## How it works

Your page requests a script from `webagent.faustine.ai` with the agent's ID. The response contains the version that the environment serves, the variable values of that environment, and the instruction to load the widget. None of it is bundled into your app.

A version you deploy or roll back in the portal therefore reaches your users on their next page load. Your app does not need a new build.

## Install methods

The **Install the assistant** card in the agent's **Overview** tab has a tab for each method, with your agent ID filled in.

| Method | Choose it when | What you add |
| --- | --- | --- |
| **JS / Auto** | The site has no build step and the widget can start as soon as the page loads. | One script tag. |
| **JS / Manual** | The site has no build step and your code decides when the widget starts, or you identify users. | A script tag for the loader and a call to `Faustine.init`. |
| **npm** | The app has a bundler. This is the recommended method for React, Vue, Angular and Svelte apps, because the calls are typed. | The `@faustine-ai/web-agent` package and a call to `Faustine.init`. |

For the first two, see [Install with a script tag](https://docs.faustine.ai/web-agents/script-tag/). For the third, see [Install from npm](https://docs.faustine.ai/web-agents/npm/).

A Next.js app uses a component from `@faustine-ai/next` and signs the user's identity on the server. See [Install in Next.js](https://docs.faustine.ai/web-agents/install-in-nextjs/).

## The agent ID

Every method needs the agent's ID. It is the `wid` value in the **JS / Auto** snippet and the `agentId` value in the other two. The ID is not a secret. To keep other sites from using it, see [Restrict the domains that can load the agent](https://docs.faustine.ai/web-agents/restrict-domains/).

![The Install the assistant card with the JS / Auto snippet and the Debug mode switch.](https://docs.faustine.ai/images/web-agents/install-card-light.png)

## The environment a page loads

An install that names no environment loads Production, or the agent's first environment while it has no Production. To load another one, name it in the install: `&env=Staging` on the script URL, or `env: 'Staging'` in `Faustine.init`. The name must match the environment's name in the **Deployments** dialog exactly.

An install that names an environment gets that environment only. If the name does not match an environment that serves a version, the agent does not load and the script request answers `404` with the reason.

## What the page needs

- A version served on the environment. Publishing the first version serves it on the release target, which is the first environment you selected in the wizard. See [Versions, environments and deployments](https://docs.faustine.ai/web-agents/versions-and-environments/).
- A domain the environment allows, if the environment has a list of allowed domains.

## Debug mode

The **Debug mode** switch on the install card adds a flag to the snippet. A page installed with it opens a debug session, which is how tests run. See [Open a debug session](https://docs.faustine.ai/web-agents/debug-sessions/).

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| No launcher, and the request to `webagent.faustine.ai/embed` returns `404` with `nothing is served for assistant` | 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. | Add the domain. See [Restrict the domains that can load the agent](https://docs.faustine.ai/web-agents/restrict-domains/). |
| The same request returns `400` with `missing ?wid=<assistantId>` | The script URL has no `wid` parameter. | Copy the snippet again from the install card. |
| The page shows an older version than the portal | The page loads an environment that still serves that version. | [Deploy the version to that environment](https://docs.faustine.ai/web-agents/deploy-a-version/). |

## Next steps

- [Install with a script tag](https://docs.faustine.ai/web-agents/script-tag/): add the widget without a build step.
- [Install from npm](https://docs.faustine.ai/web-agents/npm/): add the loader to an app with a bundler.
- [Install in Next.js](https://docs.faustine.ai/web-agents/install-in-nextjs/): mount the agent in the root layout.
- [JavaScript API](https://docs.faustine.ai/reference/javascript-api/): every option and method of the loader.