# AI 에이전트로 위젯 설치

> REST API 또는 MCP를 사용하는 코딩 에이전트에 피드백 위젯 설정과 설치를 맡깁니다.

## 개요

아래 프롬프트에는 비밀값을 넣지 않습니다. API 키는 실행 환경의 `THESEEKER_API_KEY` 환경 변수로 전달하고, 에이전트가 키 값을 출력하거나 로그에 남기지 않도록 합니다.

## 프롬프트

```text
Read and follow: https://docs.theseeker.io/feedback/ai-agent-setup.md

<context>
- API base URL: https://crm.theseeker.io/api/v1
- MCP endpoint: https://crm.theseeker.io/api/mcp
- API 키: 환경 변수 THESEEKER_API_KEY 로 전달합니다. 설정돼 있지 않으면 키 파일 경로를 저에게 물어보세요. 키 값은 절대 출력하지 마세요.
- 프로젝트 slug: <project-slug>
- 위젯을 설치할 사이트 도메인: <site-domain>
</context>

<instructions>
1. 현재 설정 확인: MCP 를 쓸 수 있으면 `get_feedback_widget` 에 `{"projectSlug":"<project-slug>"}` 를 보내고, 아니면 `GET /api/v1/feedback/widget?projectSlug=<project-slug>` 를 `Authorization: Bearer $THESEEKER_API_KEY` 로 호출합니다. 401/403 이면 중단하고 저에게 알립니다.
2. 위젯 켜기: `update_feedback_widget` 또는 `PATCH /api/v1/feedback/widget` 에 `{"projectSlug":"<project-slug>","enabled":true,"allowedDomains":[...]}` 를 보냅니다. `allowedDomains` 는 기존 값을 모두 유지하고 `<site-domain>` 을 더한 배열입니다. 표시 방식(`displayMode`)·버튼 문구 등 다른 설정은 제가 요청한 경우에만 바꿉니다.
3. 스니펫 삽입: 응답의 `install.snippet` 을 사이트의 모든 페이지가 공유하는 레이아웃의 `</body>` 바로 앞(또는 프레임워크의 동등한 위치)에 넣습니다. 프레임워크별 방법은 https://docs.theseeker.io/feedback/widget-install.md 를 따릅니다. `data-key` 의 `fbw_` 공개 키는 페이지에 노출되어도 되는 값입니다.
4. 검증: 허용 도메인에서 페이지를 열어 `/api/feedback/widget/config?key=` 요청이 200 이고, 콘솔에 `[theseeker feedback]` 경고가 없으며, 위젯이 보이는지 확인합니다. localhost 에서 확인하려면 `localhost` 도 허용 도메인에 있어야 합니다.
</instructions>

<constraints>
- API 키를 출력·로그·커밋하지 않습니다.
- 위젯 공개 키를 재발급하지 않습니다(기존 설치가 모두 끊깁니다). 재발급이 필요해 보이면 저에게 알립니다.
- 사이트의 다른 동작을 바꾸지 않습니다. 2xx 가 아닌 응답이나 예상치 못한 오류가 나면 중단하고 저에게 알립니다.
</constraints>

<verification>
보고: 프로젝트 slug, enabled, allowedDomains, displayMode, 스니펫을 넣은 파일 경로, config 요청의 상태 코드, 그리고 지시와 달라진 점.
</verification>
```

## MCP 도구

| 이름 | 권한 | 동작 |
| --- | --- | --- |
| `get_feedback_widget` | `admin:read`, `feedback:read` | 프로젝트 위젯 설정, 공개 키와 설치 스니펫을 조회합니다. |
| `update_feedback_widget` | `admin:write`, 감사 기록 | 위젯 설정을 부분 변경하고, 없으면 기본값으로 생성합니다. 공개 키는 재발급하지 않습니다. |
| `install_feedback_widget` 프롬프트 | `projectSlug`, 선택 항목 `siteDomain` | 조회와 변경 도구를 안내해 사이트 코드에 위젯을 설치합니다. |
| 앱 설치 프롬프트 | `projectSlug`, 선택 항목 `appId` | 앱 ID를 허용 앱에 등록하고 React Native SDK 설치를 안내합니다. |
| `install_feedback_widget_app` 프롬프트 | `projectSlug`, 선택 항목 `appId` | React Native·Expo 앱에 위젯을 설치하고 앱 config를 확인합니다. |

## 사이트 디자인에 맞추기

CRM 위젯 설정 패널의 에이전트 프롬프트에서 **설치 / 디자인 맞추기** 전환을 선택하면 두 번째 프롬프트를 사용할 수 있습니다. 설치 프롬프트는 위젯 활성화와 스니펫 삽입을 안내하고, **디자인 맞추기** 프롬프트는 사이트의 CSS 변수나 Tailwind·shadcn 테마를 읽어 색상, 반경, 글꼴, 문구, 테마 동작을 찾은 뒤 한 번의 PATCH로 설정하도록 안내합니다. 에이전트는 찾은 값만 적용하고, `enabled`, `allowedDomains`, `displayMode`는 요청이 없으면 바꾸지 않습니다.

다음은 사이트 디자인 값을 직접 지정하는 REST PATCH 예입니다.

```json
{
  "projectSlug": "theddari",
  "theme": "auto",
  "appearance": {
    "light": { "accent": "#5b6bd6" },
    "dark": { "accent": "#7b8af0", "background": "#17181c" },
    "radius": { "panel": 12, "field": 8, "button": 8 },
    "font": "inherit"
  },
  "texts": {
    "description": "불편한 점이나 바라는 기능을 알려주세요. 확인 후 반영하겠습니다.",
    "contactPlaceholder": "답변 받을 텔레그램 아이디 또는 이메일"
  },
  "localizedTexts": {
    "en": {
      "title": "Send Feedback",
      "contactPlaceholder": "Telegram username or email for a reply"
    }
  },
  "contactMode": "text"
}
```

`localizedTexts.en`은 사이트에 영어 페이지가 있을 때 영어 방문자에게 보일 문구입니다. 위젯 언어는 스니펫의 `data-locale` 또는 `setLocale()`로 정합니다([위젯 설치 가이드의 언어](/feedback/widget-install#언어)).

`appearance`, `texts`, `localizedTexts`는 키별로 깊은 병합됩니다. 생략한 키는 기존 값을 유지하고, 키에 `null`을 지정하면 해당 항목이 기본값으로 돌아갑니다. 그룹 전체를 `null`로 보내면 해당 그룹을 기본값으로 초기화합니다. 예를 들어 문구 설명만 기본값으로 돌리려면 다음처럼 보냅니다.

```json
{
  "projectSlug": "theddari",
  "texts": { "description": null }
}
```

## REST 예시

환경 변수에 키가 설정된 상태에서 현재 설정을 조회합니다.

```bash
curl -sS 'https://crm.theseeker.io/api/v1/feedback/widget?projectSlug=my-project' \
  -H "Authorization: Bearer $THESEEKER_API_KEY"
```

설정을 일부 변경합니다. 기존 허용 도메인을 유지하면서 새 도메인을 포함해 보내세요.

```bash
curl -sS -X PATCH https://crm.theseeker.io/api/v1/feedback/widget \
  -H "Authorization: Bearer $THESEEKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"projectSlug":"my-project","enabled":true,"allowedDomains":["example.com"]}'
```

## 하지 않는 일

API와 MCP는 공개 위젯 키를 재발급하지 않습니다. 키 재발급이 필요하다면 CRM 위젯 설정 화면에서 진행해야 하며, 기존 설치가 새 키로 갱신되기 전까지 동작을 멈출 수 있습니다.