---
title: Vue SDK
---

# Vue SDK

CaptchaLa CAPTCHA 公式の Vue 3 コンポーネント。[`@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 | 型 | デフォルト | 説明 |
|------|------|---------|-------------|
| `appKey` | `string` | *必須* | CaptchaLa の Application Key |
| `serverToken` | `string` | - | サーバー発行のワンタイム challenge トークン。アプリで `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"` のときのみ） |

## イベント

| イベント | ペイロード | 説明 |
|-------|---------|-------------|
| `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>
```

| メソッド | 説明 |
|--------|-------------|
| `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 リファレンス](/ja/api-reference) を参照してください。

## リンク

- [npm](https://www.npmjs.com/package/@captcha-la/vue) · [GitHub](https://github.com/Captcha-La/vue) · [example](https://github.com/Captcha-La/vue-example)
- [Web SDK 概要](/ja/web-sdk) · [API リファレンス](/ja/api-reference)