Szybki start z wtyczkami

Ten przewodnik pozwoli szybko przejść od pustego folderu do działającej wtyczki.

1) Utwórz minimalną wtyczkę zawierającą tylko backend

Utwórz folder z następującymi plikami:

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

Zainstaluj wtyczkę przez Wtyczki > Zainstaluj, wybierz folder, włącz wtyczkę i sprawdź, czy w dziennikach pojawia się Plugin started.

2) Jeśli używasz TypeScript

Użyj następującej struktury:

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

Połącz kod w jeden plik za pomocą:

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

Następnie zainstaluj folder tak jak powyżej.

3) Dodaj frontend później

Dodaj wpis frontendu i pliki interfejsu dopiero wtedy, gdy potrzebujesz panelu:

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

Następnie rozszerz manifest.json o:

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

Do komunikacji frontendu używaj window.ogmaSDK.ready(...), a wywołania backendu umieszczaj w procedurach obsługi sdk.api.

4) Uprawnienia, których niemal zawsze potrzebujesz

Dla powyższego przykładu backendu:

• żadne (bezpieczne uprawnienia domyślne są przyznawane automatycznie)

Jeśli wtyczka wysyła żądania wychodzące, dodaj:

"permissions": ["send_requests"]

Jeśli wtyczka zapisuje ustalenia, dodaj:

"permissions": ["write_findings"]

Żądaj tylko tych uprawnień, z których faktycznie korzystasz.

Rozwiązywanie problemów z pierwszą wtyczką

• Plugin failed to initialize → otwórz Dzienniki i sprawdź, czy zdefiniowano init(sdk).
• Invalid manifest → sprawdź przecinki i cudzysłowy w JSON.
• Funkcje zwrotne nie są wywoływane → sprawdź, czy wtyczka jest włączona i czy zarejestrowano odpowiednie zdarzenie (onInterceptResponse).

Pełna dokumentacja referencyjna API:

• System wtyczek
• SDK backendu
• SDK frontendu