---
url: https://docs.ogmabox.com/vi/plugins/quickstart.md
description: >-
  Tạo và cài đặt plugin Ogma đầu tiên trong vài phút với ví dụ backend tối giản
  và bảng frontend tùy chọn.
---

# Bắt đầu nhanh với plugin {#plugin-quickstart}

Hướng dẫn này giúp bạn nhanh chóng chuyển từ một thư mục trống sang plugin đang chạy.

## 1) Tạo plugin tối giản chỉ có backend {#\_1-create-a-minimal-backend-only-plugin}

Tạo một thư mục chứa các tệp sau:

```text
my-plugin/
  manifest.json
  backend/
    script.js
```

`manifest.json`:

```json
{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "0.1.0",
  "plugins": [
    {
      "kind": "backend",
      "id": "my-plugin-backend",
      "entrypoint": "backend/script.js"
    }
  ]
}
```

`backend/script.js`:

```js
async function init(sdk) {
  sdk.console.log("Plugin started");

  sdk.events.onInterceptResponse(function(req, res) {
    if (!res) return;
    if (res.getCode() === 403) {
      sdk.console.warn("403 on " + req.getUrl());
    }
  });
}
```

Cài đặt từ **Plugin > Cài đặt**, chọn thư mục, bật plugin và kiểm tra nhật ký có hiển thị `Plugin started`.

## 2) Nếu bạn dùng TypeScript {#\_2-if-you-are-using-typescript}

Dùng cấu trúc sau:

```text
my-plugin/
  manifest.json
  backend/
    src/index.ts
```

Tạo bundle bằng:

```bash
pnpm add -D @ogmabox/ogma-sdk esbuild typescript
pnpm exec esbuild backend/src/index.ts \
  --bundle \
  --platform=neutral \
  --format=iife \
  --external:@ogma/sdk --external:@ogmabox/ogma-sdk \
  --outfile=backend/script.js
```

Sau đó cài đặt thư mục như hướng dẫn ở trên.

## 3) Thêm frontend sau {#\_3-add-a-frontend-later}

Chỉ thêm mục frontend và các tệp giao diện khi bạn cần một bảng giao diện:

```text
my-plugin/
  frontend/
    script.js
    style.css   # optional
```

Sau đó mở rộng `manifest.json` bằng:

```json
{
  "kind": "frontend",
  "id": "my-plugin-frontend",
  "entrypoint": "frontend/script.js",
  "backend": { "id": "my-plugin-backend" }
}
```

Để frontend giao tiếp, dùng `window.ogmaSDK.ready(...)` và đặt các lệnh gọi backend trong hàm xử lý `sdk.api`.

## 4) Các quyền bạn gần như luôn cần {#\_4-permissions-you-almost-always-need}

Đối với ví dụ backend ở trên:

* không cần quyền nào (các quyền mặc định an toàn được cấp tự động)

Nếu plugin của bạn gửi yêu cầu ra ngoài, thêm:

```json
"permissions": ["send_requests"]
```

Nếu plugin của bạn ghi phát hiện, thêm:

```json
"permissions": ["write_findings"]
```

Chỉ yêu cầu quyền bạn thực sự dùng.

## Khắc phục sự cố với plugin đầu tiên {#troubleshooting-first-plugin}

* `Plugin failed to initialize` → mở **Nhật ký** và xác nhận `init(sdk)` đã được định nghĩa.
* `Invalid manifest` → kiểm tra dấu phẩy và dấu ngoặc kép trong JSON.
* Không có callback nào được chạy → xác nhận plugin đã được bật và sự kiện tương ứng (`onInterceptResponse`) đã được đăng ký.

Để xem tài liệu tham khảo API đầy đủ:

* [Hệ thống plugin](./README)
* [SDK backend](/vi/plugins/backend-sdk)
* [SDK frontend](/vi/plugins/frontend-sdk)