Bắt đầu nhanh với plugin

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

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

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

manifest.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:

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

Dùng cấu trúc sau:

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

Tạo bundle bằng:

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

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:

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

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

{
  "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

Đố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:

"permissions": ["send_requests"]

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

"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

• 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
• SDK backend
• SDK frontend