---
title: Vue SDK
---

# Vue SDK

Component Vue 3 chính thức cho CaptchaLa CAPTCHA — phát hành dưới dạng [`@captcha-la/vue`](https://www.npmjs.com/package/@captcha-la/vue).

## Demo trực tiếp

::: tip 📦
[demo-v1.captcha.la/vue](https://demo-v1.captcha.la/vue/) — demo chạy được với cả bốn chế độ sản phẩm.
Mã nguồn: [Captcha-La/vue-example](https://github.com/Captcha-La/vue-example).
:::

## Cài đặt

```bash
npm install @captcha-la/vue
# hoặc
yarn add @captcha-la/vue
# hoặc
pnpm add @captcha-la/vue
```

Peer dependency: `vue@^3.2.0`.

## Bắt đầu nhanh

```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) {
  // Gửi result.token đến máy chủ của bạn để xác minh.
  console.log('pass_token:', result.token)
}

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

## Props

| Prop | Kiểu | Mặc định | Mô tả |
|------|------|---------|-------------|
| `appKey` | `string` | *bắt buộc* | Khóa ứng dụng CaptchaLa |
| `serverToken` | `string` | - | Token thử thách do máy chủ phát hành, dùng một lần. Bắt buộc khi ứng dụng có `server_token_required=true`. |
| `product` | `'popup' \| 'float' \| 'embed' \| 'bind'` | `'popup'` | Chế độ hiển thị |
| `action` | `string` | `'default'` | Định danh hành động (ví dụ `login`, `register`, `checkout`) |
| `lang` | `string` | `'zh-CN'` | Mã ngôn ngữ (`zh-CN`, `en`, `ja`, …) |
| `bindTo` | `string \| HTMLElement` | - | Selector hoặc node để gắn vào (chỉ cho `product="bind"`) |

## Sự kiện

| Sự kiện | Payload | Mô tả |
|-------|---------|-------------|
| `success` | `{ token, type, action }` | Xác minh thành công |
| `error` | `error` | Xác minh thất bại |
| `close` | — | CAPTCHA bị đóng |
| `ready` | — | CAPTCHA sẵn sàng |

## Phương thức (qua `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>
```

| Phương thức | Mô tả |
|--------|-------------|
| `verify()` | Kích hoạt xác minh |
| `reset()` | Đặt lại trạng thái CAPTCHA |
| `destroy()` | Hủy instance |
| `bindTo(selector)` | Gắn vào phần tử (cho chế độ `bind`) |
| `setLang(lang)` | Đổi ngôn ngữ tại chỗ |

## Production: chế độ `serverToken`

Đối với các luồng quan trọng (đăng nhập, đăng ký, thanh toán), chúng tôi khuyến nghị
**luồng token do máy chủ phát hành**. Backend của bạn phát hành một `server_token` dùng một lần
(TTL 5 phút) qua `POST /v1/server/challenge/issue` và trao nó cho trình duyệt:

```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')   // backend của bạn
  serverToken.value = (await r.json()).server_token
})

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

Xem [Tài liệu API](/vi/api-reference) để biết toàn bộ hợp đồng phía backend.

## Liên kết

- [npm](https://www.npmjs.com/package/@captcha-la/vue) · [GitHub](https://github.com/Captcha-La/vue) · [ví dụ](https://github.com/Captcha-La/vue-example)
- [Tổng quan Web SDK](/vi/web-sdk) · [Tài liệu API](/vi/api-reference)