Plugin einreichen

Dies ist die operative Anleitung fuer das Versenden eines Plugins an den Levy Fleets-Marktplatz. Lesen Sie zuerst die Uebersicht zum Entwicklerportal fuer den Kontext zur Plattform und zum Umsatzmodell.

Schritt 1 - Als Anbieter registrieren

Gehen Sie zu /developers und klicken Sie auf Registrieren.

Sie geben an:

• Anbietername - erscheint auf Plugin-Karten
• Kontakt-E-Mail - fuer Review-Benachrichtigungen, nicht oeffentlich angezeigt
• Support-E-Mail - oeffentlich angezeigt, wohin Betreiber Probleme senden
• Homepage-URL
• Logo - 256x256 PNG, quadratisch, transparenter Hintergrund

Wir senden eine Verifizierungs-E-Mail. Nach der Verifizierung unterzeichnen Sie die Plugin-Partnervereinbarung (Standardbedingungen, ca. 5 Minuten zum Lesen).

Schritt 2 - Stripe Connect einrichten (nur kostenpflichtige Plugins)

Wenn Ihr Plugin etwas berechnet (einmalig, monatlich oder Nutzung), steigen Sie mit Stripe Connect Express ein. Vom Anbieter-Dashboard:

1. Klicken Sie auf Auszahlungen einrichten
2. Stripe oeffnet seinen Onboarding-Fluss
3. Geben Sie Geschaeftsinformationen, Bankkonto und Steuerinformationen an (ca. 10 Minuten)
4. Stripe verifiziert - typischerweise am selben Tag fuer die USA, 1-3 Tage international

Kostenlose Plugins koennen diesen Schritt ueberspringen.

Schritt 3 - Ihr Webhook-Endpunkt erstellen

Ihr Plugin benoetigt einen HTTPS-Endpunkt, der signierte POSTs von Levy akzeptiert. Mindestimplementierung:

import crypto from 'crypto';

const PLUGIN_SECRET = process.env.LEVY_PLUGIN_SECRET!; // aus Ihrem Anbieter-Dashboard

export async function POST(request: Request) {
  const sig = request.headers.get('x-levy-signature');
  const body = await request.text();

  if (!verifyLevySignature(body, sig, PLUGIN_SECRET)) {
    return new Response('Invalid signature', { status: 401 });
  }

  const event = JSON.parse(body);
  // event.event_type, event.data behandeln
  return new Response('ok');
}

function verifyLevySignature(body: string, header: string | null, secret: string) {
  if (!header) return false;
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const ts = parts.t;
  const v1 = parts.v1;
  if (!ts || !v1) return false;
  // ablehnen, wenn aelter als 5 Minuten
  if (Math.abs(Date.now() / 1000 - parseInt(ts, 10)) > 300) return false;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${ts}.${body}`)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

Levy versucht fehlgeschlagene Zustellungen 5 Mal mit exponentiellem Backoff erneut (1m, 5m, 30m, 2h, 12h). Antworten Sie innerhalb von 30 Sekunden mit HTTP 2xx. Alles andere wird als Fehler behandelt.

Schritt 4 - Ihr Manifest erstellen

Erstellen Sie plugin.json im Stammverzeichnis Ihres Projekts. Minimalbeispiel:

{
  "slug": "my-fraud-scorer",
  "version": "1.0.0",
  "name": "My Fraud Scorer",
  "vendor": {
    "name": "Acme Fraud Inc",
    "email": "support@acmefraud.com",
    "url": "https://acmefraud.com"
  },
  "category": "other",
  "description": "Bewertet jede Fahrt nach Betrugsrisiko und schreibt einen Flag zurueck zu Levy.",
  "long_description_mdx": "# Acme Fraud Scorer\n\nBewertet Fahrten...",
  "screenshots": [
    "https://cdn.acmefraud.com/screenshots/dashboard.png"
  ],
  "homepage": "https://acmefraud.com",
  "support_url": "https://acmefraud.com/support",
  "permissions": ["read:rides", "read:rides.geo", "write:rides.flags"],
  "webhook_subscriptions": ["ride.ended"],
  "webhook_endpoint": "https://api.acmefraud.com/levy/webhook",
  "config_schema": {
    "type": "object",
    "required": ["api_key"],
    "properties": {
      "api_key": {
        "type": "string",
        "title": "Acme Fraud API-Schluessel",
        "description": "Finden Sie dies in Ihrem Acme Fraud-Konto -> Einstellungen -> API"
      },
      "threshold": {
        "type": "number",
        "title": "Risikoschwelle (0-100)",
        "default": 70
      }
    }
  },
  "pricing": {
    "model": "usage",
    "unit": "bewertete Fahrt",
    "unit_amount_cents": 5,
    "currency": "USD"
  }
}

config_schema-Tipps

• Verwenden Sie title und description bei jedem Feld - sie werden Betreibern im Installationsformular angezeigt.
• Markieren Sie erforderliche Felder mit required: ["field_name"].
• Verwenden Sie format: "password" fuer API-Schluessel - Levy rendert sie als maskierte Eingaben.
• Verwenden Sie enums fuer Auswahllisten: "enum": ["option_a", "option_b"].
• Verwenden Sie format: "uri" fuer URLs, um Inline-Validierung zu erhalten.

Tipps zur Berechtigungsauswahl

Betreiber sehen Ihre Berechtigungen in klarer Sprache. Jeder Scope, den Sie anfordern, macht den Installationsdialog laenger und einschuechternder. Die beste Strategie: fragen Sie nach dem Minimum und erklaeren Sie warum in Ihrem long_description_mdx.

Schritt 5 - In der Sandbox testen

Fordern Sie aus dem Anbieter-Dashboard Sandbox-Zugang an. Sie erhalten ein Sandbox-Subkonto mit synthetischen Daten.

Testen Sie diese Szenarien:

1. Aus Sandbox-Marktplatz installieren - Ihr Plugin erscheint im Sandbox-Marktplatz, sobald eingereicht.
2. Ein Testereignis feuern - verwenden Sie Anbieter-Dashboard -> Sandbox -> Testereignis feuern, um ein synthetisches ride.ended an Ihren Endpunkt zu senden. Pruefen Sie, ob Ihre Signaturpruefung besteht und Ihr Handler das Richtige tut.
3. Konfigurationsformular testen - rendert es korrekt? Sind Validierungsfehler klar?
4. OAuth testen (falls zutreffend) - leitet die authorize_url korrekt weiter? Akzeptiert die token_url den Authentifizierungscode?
5. Webhook-Fehlerbehandlung testen - geben Sie einmal eine 500 von Ihrem Endpunkt zurueck. Pruefen Sie, ob Levy es erneut versucht und die Installation schliesslich als fehlerhaft markiert.

Schritt 6 - Zur Pruefung einreichen

Klicken Sie im Anbieter-Dashboard auf Zur Pruefung einreichen. Laden Sie hoch:

• Ihr plugin.json (gegen Schema geparst)
• Alle Screenshot-URLs (verifiziert zugaenglich)
• Ihre lange Beschreibung (Markdown, max. 20 KB)
• Preisdetails zur Bestaetigung
• Eine kurze Notiz an den Pruefer (optional, hilfreich fuer Kontext - "dies ist v2 mit dem neuen Sandbox-Fluss")

Die Einreichung geht in die Levy-Ops-Review-Warteschlange ueber. Sie erhalten E-Mail-Updates, waehrend sie voranschreitet.

Schritt 7 - Review-Feedback adressieren

Der Pruefer genehmigt Ihr Plugin entweder oder fordert Aenderungen an. Haeufige Anfragen:

• Berechtigungsumfang reduzieren - "Ihr Plugin fragt nach read:customers.pii, aber die Manifestbeschreibung rechtfertigt es nicht. Entfernen Sie entweder den Scope oder erweitern Sie die Beschreibung."
• Beschreibung verbessern - "die Beschreibung erklaert nicht, was dieses Plugin in klarer Sprache tut."
• Screenshots hinzufuegen - "wir benoetigen mindestens einen Screenshot, der das Plugin in Aktion zeigt."
• Signaturpruefung beheben - "wir haben ein Testereignis mit einer schlechten Signatur gesendet und Ihr Endpunkt gab 200 zurueck. Bitte verifizieren Sie Signaturen korrekt."
• Preise anpassen - "999 $/Monat ist das Maximum, es sei denn, Sie haben eine benutzerdefinierte Vereinbarung. Senken Sie entweder den Preis oder kontaktieren Sie uns wegen einer Ausnahme."

Reichen Sie erneut ein, indem Sie Ihr Plugin im Dashboard aktualisieren und auf Erneut einreichen klicken. Die 5-Tage-SLA-Uhr startet neu; Wiedereinreichungen werden normalerweise in 1-2 Tagen abgeschlossen.

Schritt 8 - Start

Nach der Genehmigung geht Ihr Plugin innerhalb von Minuten live im Marktplatz. Betreiber koennen sofort installieren. Sie sehen Installationsanzahl und aktive Installationen auf Ihrem Anbieter-Dashboard.

Wir empfehlen einen sanften Start:

• Verifizieren Sie leise, dass die ersten 5 Installationen End-to-End funktionieren
• Beobachten Sie die Webhook-Erfolgsrate
• Beheben Sie Produktionsprobleme vor der Bewerbung
• Dann bewerben Sie ueber Ihre Kanaele (LinkedIn, Ihre bestehenden Kunden usw.)

Levy kann Ihr Plugin gemeinsam vermarkten, wenn es strategisch wertvoll ist - wenden Sie sich an partnerships@levyelectric.com, um sich abzustimmen.

Versionierung nach dem Start

• Patch (1.0.0 -> 1.0.1) - Bugfixes, keine API-Aenderungen. Automatische Upgrades fuer alle Installationen.
• Minor (1.0.0 -> 1.1.0) - neue optionale Funktionen, neue optionale Konfigurationsfelder. Automatische Upgrades.
• Major (1.0.0 -> 2.0.0) - breaking Changes (neue erforderliche Berechtigungen, entfernte Konfigurationsfelder, geaendertes Webhook-Payload-Format). Betreiber sehen ein Banner, das sie auffordert, erneut zuzustimmen. Die alte Version funktioniert weiter, bis sie aktualisieren.

Verwenden Sie semver verantwortungsbewusst. Major-Bumps sind Reibung - buendeln Sie mehrere breaking Changes in einem Release.

Was kommt als naechstes

• Entwicklerportal - Uebersicht, Vereinbarungen, Sandbox
• Plugin-Abrechnung - wie Stripe-Connect-Auszahlungen funktionieren