---
title: Vue SDK
---

# Vue SDK

CaptchaLa CAPTCHA를 위한 공식 Vue 3 컴포넌트입니다. npm에 [`@captcha-la/vue`](https://www.npmjs.com/package/@captcha-la/vue)로 배포되어 있습니다.

## 라이브 데모

::: tip 📦
[demo-v1.captcha.la/vue](https://demo-v1.captcha.la/vue/) — 4 가지 product 모드를 모두 포함한 실행 가능한 데모입니다.
소스: [Captcha-La/vue-example](https://github.com/Captcha-La/vue-example).
:::

## 설치

```bash
npm install @captcha-la/vue
# 또는
yarn add @captcha-la/vue
# 또는
pnpm add @captcha-la/vue
```

Peer dependency: `vue@^3.2.0`.

## 빠른 시작

```vue
<template>
  <Captchala
    app-key="your-app-key"
    product="popup"
    @success="handleSuccess"
    @error="handleError"
  />
</template>

<script setup>
import { Captchala } from '@captcha-la/vue'

function handleSuccess(result) {
  // result.token 을 서버로 전송하여 검증하십시오.
  console.log('pass_token:', result.token)
}

function handleError(error) {
  console.error('verification failed:', error)
}
</script>
```

## Props

| Prop | Type | Default | 설명 |
|------|------|---------|-------------|
| `appKey` | `string` | *필수* | CaptchaLa 애플리케이션 키 |
| `serverToken` | `string` | - | 서버에서 발급한 일회용 챌린지 토큰입니다. 앱이 `server_token_required=true` 인 경우 필수입니다. |
| `product` | `'popup' \| 'float' \| 'embed' \| 'bind'` | `'popup'` | 표시 모드 |
| `action` | `string` | `'default'` | 액션 식별자 (예: `login`, `register`, `checkout`) |
| `lang` | `string` | `'zh-CN'` | 언어 코드 (`zh-CN`, `en`, `ja`, …) |
| `bindTo` | `string \| HTMLElement` | - | 바인딩할 엘리먼트 셀렉터 또는 노드 (`product="bind"` 에서만 사용) |

## 이벤트

| Event | Payload | 설명 |
|-------|---------|-------------|
| `success` | `{ token, type, action }` | 검증 성공 |
| `error` | `error` | 검증 실패 |
| `close` | — | CAPTCHA 닫힘 |
| `ready` | — | CAPTCHA 준비 완료 |

## 메서드 (`ref` 경유)

```vue
<template>
  <Captchala ref="captchaRef" app-key="your-app-key" />
  <button @click="captchaRef?.verify()">Verify</button>
</template>

<script setup>
import { ref } from 'vue'
const captchaRef = ref()
</script>
```

| Method | 설명 |
|--------|-------------|
| `verify()` | 검증을 트리거합니다 |
| `reset()` | CAPTCHA 상태를 재설정합니다 |
| `destroy()` | 인스턴스를 파괴합니다 |
| `bindTo(selector)` | 엘리먼트에 바인딩합니다 (`bind` 모드용) |
| `setLang(lang)` | 언어를 즉시 변경합니다 |

## 프로덕션: `serverToken` 모드

가치가 높은 플로우(로그인, 회원가입, 결제)에는 **서버 발급 토큰 플로우**를
권장합니다. 백엔드에서 `POST /v1/server/challenge/issue` 로 일회용 `server_token`
(TTL 5 분)을 발급한 뒤 브라우저로 전달합니다:

```vue
<template>
  <Captchala
    v-if="serverToken"
    :server-token="serverToken"
    app-key="pk_your_public_app_key"
    action="login"
    @success="onSuccess"
  />
</template>

<script setup>
import { ref, onMounted } from 'vue'
import { Captchala } from '@captcha-la/vue'

const serverToken = ref()

onMounted(async () => {
  const r = await fetch('/api/captcha-token')   // 자체 백엔드
  serverToken.value = (await r.json()).server_token
})

function onSuccess(result) {
  console.log('pass_token:', result.token)
}
</script>
```

백엔드 계약 전체는 [API 레퍼런스](/ko/api-reference)를 참조하십시오.

## 링크

- [npm](https://www.npmjs.com/package/@captcha-la/vue) · [GitHub](https://github.com/Captcha-La/vue) · [예제](https://github.com/Captcha-La/vue-example)
- [Web SDK 개요](/ko/web-sdk) · [API 레퍼런스](/ko/api-reference)