البدء السريع للإضافات

ينقلك هذا الدليل بسرعة من مجلد فارغ إلى إضافة تعمل.

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 الواجهة الأمامية