replypier/replypier-test/README.md

# ReplyPier Widget Test

This is a test project for the ReplyPier chat widget integration.

## UI options gallery

`ui-options.html` has one card per widget placement/behaviour (floating left/right,
custom size and offsets, sidebar drawers, search-bar trigger, hidden launcher + own
button, custom z-index, dashboard defaults, page-overrides-beat-dashboard, mobile).
Each opens `ui-test.html` with that configuration plus buttons for the whole JS API
(`open/close/toggle/isOpen`, `open({message})`, `hide/showLauncher`, `setPosition`,
`data-replypier-open`, `trigger` selector) and an event log.

Use it in **Stub** mode (fake widget, no backend needed) or **Real** mode (set your
widget ID + API URL on the gallery page). The Loader URL setting controls where
`replypier.min.js` comes from — the frontend dev server by default.

## Setup

1. Install dependencies:

```bash
npm install
```

2. Start the test server:

```bash
npm start
```

3. Open http://localhost:3000 in your browser

## Testing the Widget

1. Make sure the ReplyPier frontend development server is running (usually at http://localhost:5173)
2. Click the "Initialize Widget" button on the test page
3. Use the chat widget that appears in the bottom-right corner

## Development Notes

- The widget script is loaded from the local development server
- The test page uses a dummy widget ID ('test-widget-123')
- CORS is enabled to allow loading the widget script from a different origin

## Where things are served from

- **Loader** (`replypier.min.js`) — the **frontend** (`http://localhost:5173/webclient/…`),
  the same origin the dashboard's embed snippet points at. The backend does **not**
  serve it, and no copy is kept in this folder: a copy goes stale and you end up
  testing an old widget while the source looks correct.
  It is a build artifact — after editing `frontend/src/webclient/replypier.js` run
  `cd ../frontend && npm run build:webclient:prod`.
- **Widget app** (`widget.js`) — the backend, from `backend/assets/`. Rebuild with
  `cd ../frontend && npm run build:widget:prod` after changing `WidgetBuilder.vue`
  or the widget composables.
- **API** — set `window.replypierBaseUrl`. Without it the loader falls back to the URL
  baked in at build time, which for a production build is the cloud API, so a "local"
  test silently talks to api.replypier.site.

## Troubleshooting

- **“客服暂时无法连接”** — check the browser console and the widget-data request in
  Network for network, HTTP, or CORS failures. If the request was rejected by CORS,
  check the page origin against the organization's allowed domain, including its port.
- **Dashboard placement settings not applying** — almost always a stale loader. Check the
  served file has the newer features: `curl -s <loader-url> | grep -c sidebar-left`.
- **Buttons do nothing on the gallery pages** — the loader failed to load; the page shows
  a red banner saying so.