شروع سریع افزونه‌ها

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

1) ساخت یک افزونهٔ ساده فقط برای بک‌اند

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

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

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

2) اگر از TypeScript استفاده می‌کنید

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

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

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

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) افزودن فرانت‌اند در آینده

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

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

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

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

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

4) مجوزهایی که تقریباً همیشه نیاز دارید

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

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

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

"permissions": ["send_requests"]

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

"permissions": ["write_findings"]

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

رفع اشکال نخستین افزونه

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

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

• نظام افزونه‌ها
• SDK بک‌اند
• SDK فرانت‌اند