---
url: https://docs.ogmabox.com/fa/plugins/quickstart.md
description: >-
  نخستین افزونهٔ Ogma خود را در چند دقیقه با یک نمونهٔ سادهٔ بک‌اند و پنل
  اختیاری فرانت‌اند بسازید و نصب کنید.
---

# شروع سریع افزونه‌ها {#plugin-quickstart}

این راهنما شما را به‌سرعت از یک پوشهٔ خالی به افزونه‌ای در حال اجرا می‌رساند.

## 1) ساخت یک افزونهٔ ساده فقط برای بک‌اند {#\_1-create-a-minimal-backend-only-plugin}

پوشه‌ای با این فایل‌ها بسازید:

```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());
    }
  });
}
```

از مسیر **افزونه‌ها > نصب** نصب کنید، پوشه را انتخاب و افزونه را فعال کنید و بررسی کنید که `Plugin started` در گزارش رویدادها دیده شود.

## 2) اگر از TypeScript استفاده می‌کنید {#\_2-if-you-are-using-typescript}

از این ساختار استفاده کنید:

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

با فرمان زیر بسته‌بندی کنید:

```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
```

سپس پوشه را مانند بالا نصب کنید.

## 3) افزودن فرانت‌اند در آینده {#\_3-add-a-frontend-later}

تنها وقتی به پنل نیاز دارید، یک ورودی فرانت‌اند و فایل‌های رابط کاربری اضافه کنید:

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

سپس `manifest.json` را با این موارد گسترش دهید:

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

برای ارتباط فرانت‌اند از `window.ogmaSDK.ready(...)` استفاده کنید و فراخوانی‌های بک‌اند را در پردازشگرهای `sdk.api` نگه دارید.

## 4) مجوزهایی که تقریباً همیشه نیاز دارید {#\_4-permissions-you-almost-always-need}

برای نمونهٔ بک‌اند بالا:

* هیچ مجوزی لازم نیست (مجوزهای پیش‌فرض ایمن به‌طور خودکار اعطا می‌شوند)

اگر افزونهٔ شما درخواست‌های خروجی ارسال می‌کند، اضافه کنید:

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

اگر افزونهٔ شما یافته‌ها را می‌نویسد، اضافه کنید:

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

فقط آنچه واقعاً استفاده می‌کنید درخواست کنید.

## رفع اشکال نخستین افزونه {#troubleshooting-first-plugin}

* `Plugin failed to initialize` ← **گزارش رویدادها** را باز کنید و مطمئن شوید `init(sdk)` تعریف شده است.
* `Invalid manifest` ← ویرگول‌ها و علامت‌های نقل‌قول JSON را بررسی کنید.
* توابع فراخوانی برگشتی اجرا نمی‌شوند ← مطمئن شوید افزونه فعال است و رویداد متناظر (`onInterceptResponse`) ثبت شده است.

برای مراجع کامل API:

* [نظام افزونه‌ها](./README)
* [SDK بک‌اند](/fa/plugins/backend-sdk)
* [SDK فرانت‌اند](/fa/plugins/frontend-sdk)