התחלה מהירה עם תוספים

מדריך זה מביא אתכם במהירות מתיקייה ריקה לתוסף פועל.

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 של צד הלקוח