온보딩과 설정 프로토콜 통합하기: CLI부터 웹까지 하나의 흐름으로

새로운 도구를 도입할 때 CLI와 웹 대시보드의 설정 방식이 제각각이라 당황스러웠던 적이 있나요? 환경마다 다른 설정 방식을 관리하다 보면 실수가 생기기 마련이고, 이는 곧 개발자 경험이 나빠지는 결과로 이어집니다. 모든 플랫폼에서 동일한 로직으로 설정을 관리할 수 있다면 이런 고민을 덜 수 있습니다.

이 글에서는 Wizard 엔진을 통해 여러 클라이언트에서 일관된 온보딩과 설정 경험을 구현하는 방법을 소개할게요.

필요한 것

시작하기 전에 다음 항목들이 준비되어 있는지 확인해 주세요.

• Gateway RPC 인터페이스
• JSON Schema 기반의 설정 데이터 및 UI Hints

빠른 시작

단 5분 만에 온보딩 프로세스를 시작하는 방법이에요. Gateway RPC를 통해 Wizard 엔진을 제어하면 됩니다.

1. 온보딩 세션 시작하기

wizard.start API를 호출해 세션을 생성합니다. 로컬이나 원격 모드를 선택할 수 있어요.

// Request
{
  "jsonrpc": "2.0",
  "method": "wizard.start",
  "params": {
    "mode": "local",
    "workspace": "/path/to/workspace"
  },
  "id": 1
}

2. 다음 단계로 진행하기

사용자가 입력한 값을 wizard.next로 전달해 다음 단계로 넘어갑니다.

// Request
{
  "jsonrpc": "2.0",
  "method": "wizard.next",
  "params": {
    "sessionId": "session-id-123",
    "answer": {
      "stepId": "welcome-step",
      "value": "confirmed"
    }
  },
  "id": 2
}

3. 설정 스키마 가져오기

UI를 구성하기 위해 config.schema를 호출하여 JSON Schema와 UI Hints를 받아옵니다.

// Request
{
  "jsonrpc": "2.0",
  "method": "config.schema",
  "params": {},
  "id": 3
}

문제 해결

진행 중 문제가 발생하면 다음 내용을 확인해 보세요.

• 지원되지 않는 스키마 노드: UI에서 특정 스키마 노드를 해석하지 못할 경우, 시스템은 자동으로 raw JSON editor를 띄워 사용자가 직접 수정할 수 있게 합니다.
• 민감한 정보 노출: uiHints에서 sensitive로 표시된 필드는 비밀번호 입력창으로 렌더링되지만, 별도의 마스킹(redaction) 레이어는 없으니 주의가 필요합니다.

더 자세한 도움이 필요하다면 AI Setup Assistant에게 질문해 주세요!

다음 단계

• Gateway RPC 상세 명세
• UI Hints 설정 가이드