Entwickler · API

Plugin-API: verbinde deinen Spielserver

Verbinde deinen Game-Server (Minecraft, Rust, ARK…) mit deiner Kampagne: Der Fortschritt erscheint im Spiel und Belohnungen werden automatisch vergeben.

GET/api/plugin/campaignGET/api/plugin/donations

1. Authentifizierung

Schlüssel erstellen

In deinem Dashboard: Kampagne → Tab Bearbeiten → „In-Game-Plugin“ → Schlüssel erstellen. Der vollständige Schlüssel (ka_live_…) wird nur einmal angezeigt: kopiere ihn und füge ihn in die Plugin-Konfiguration ein.

Ein Schlüssel gilt für eine einzige Kampagne / einen einzigen Server.
Nur der SHA-256-Hash wird gespeichert: niemand kann deinen Schlüssel auslesen. Verloren? Erstelle einen neuen.
Du kannst einen Schlüssel jederzeit widerrufen; er funktioniert sofort nicht mehr.

Schlüssel verwenden

Sende den Schlüssel im Authorization-Header jeder Anfrage:

header

Authorization: Bearer ka_live_xxxxxxxxxxxxxxxxxxxxxxxx

Sicherheit: der Schlüssel ist ein Server-Geheimnis. Nie in einen Spiel-Client, ein öffentliches Repo oder etwas für Spieler Zugängliches legen.

2. Grundlagen

Basis-URL	`https://keepalive.gg` · lokal `http://localhost:3100`
Format	JSON für Anfragen und Antworten.
Rate-Limit	~120 Anfragen / Minute pro Schlüssel. Darüber → `429`.
Polling	Ein Intervall von 30 bis 60 s reicht völlig.

Fehler folgen einem Standardformat: { "error": { "code", "message" } }

401Fehlender, ungültiger oder widerrufener Schlüssel.
404Die Kampagne existiert nicht mehr.
429Zu viele Anfragen, versuche es gleich erneut.

GET/api/plugin/campaign

Gibt den Fortschritt der mit dem Schlüssel verknüpften Kampagne zurück; rufe ihn regelmäßig auf, um die Anzeige im Spiel zu aktualisieren.

cURL

curl https://keepalive.gg/api/plugin/campaign \
  -H "Authorization: Bearer ka_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Antwort 200

{
  "campaign": {
    "slug": "skycraft-survie",
    "title": "SkyCraft Survie",
    "game": "minecraft",
    "status": "published",
    "goalKind": "monthly",
    "goalCents": 2000,
    "currency": "EUR",
    "raisedCents": 1450,
    "pct": 73,
    "supporters": 12,
    "rewards": [
      { "minCents": 500, "title": "Role", "description": "…" }
    ]
  }
}

goalCents / raisedCents sind in Cent · pct bereits auf 0 bis 100 begrenzt · goalKind ist monthly oder oneshot.

GET/api/plugin/donations

Listet eingezogene Spenden auf, älteste zuerst, um Belohnungen zu vergeben. Der Cursor vermeidet das erneute Laden alter Spenden.

Param	Standard	Beschreibung
`after`	keiner	Opaker Cursor: der `nextCursor` der vorherigen Seite. Beim ersten Aufruf weglassen.
`limit`	50	Max. Anzahl Spenden (auf 50 begrenzt).

cURL

curl "https://keepalive.gg/api/plugin/donations?after=CURSOR" \
  -H "Authorization: Bearer ka_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Antwort 200

{
  "donations": [
    {
      "id": "don_9f2c…",
      "donorName": "Nova",
      "amountCents": 1000,
      "currency": "EUR",
      "message": "gg",
      "recurring": false,
      "rewardTitle": "Kit VIP",
      "createdAt": "2026-07-21T18:04:11.000Z"
    }
  ],
  "nextCursor": "2026-07-21T18:04:11.000Z|don_9f2c…"
}

Ausgegebene Felder (nur öffentlich):

Feld	Beschreibung
`id`	Eindeutige Spenden-ID (dient zur Deduplizierung).
`donorName`	Öffentlicher Name des Spenders (`null` wenn anonym).
`amountCents`	Spendenbetrag, in Cent.
`message`	Öffentliche Nachricht des Spenders (`null` wenn keine).
`recurring`	`true` bei einer monatlichen Spende.
`rewardTitle`	Freigeschaltete Stufe, die im Spiel vergeben wird (`null` wenn keine).
`createdAt`	ISO-8601-Datum.

Nie eine E-Mail, eine Stripe-ID oder der Nettobetrag: nur was auf der Kampagnenseite ohnehin öffentlich ist.

Empfohlene Polling-Schleife

Pseudocode

cursor = cursor_laden()              # beim ersten Start leer
verarbeitete_ids = ids_laden()       # Anti-Duplikat

alle 30 bis 60 s:
  page = GET /api/plugin/donations?after=cursor
  für jede Spende in page.donations:
    wenn Spende.id schon verarbeitet: weiter
    wenn Spende.rewardTitle und Spende.donorName:
      spieler = spieler_finden(Spende.donorName)
      wenn spieler: belohnung_geben(spieler, Spende.rewardTitle)
    Spende.id als verarbeitet markieren
  wenn page.nextCursor:
    cursor = page.nextCursor ; speichern(cursor)

Immer nach id deduplizieren: vergib dieselbe Belohnung nie zweimal, auch nicht an der Cursor-Grenze.

3. Die Belohnung dem richtigen Spieler zuweisen

KeepAlive kennt das Spielkonto des Spenders nicht, nur den öffentlichen Namen, den er eingegeben hat (donorName). Die empfohlene Konvention:

Bitte deine Spieler, mit ihrem In-Game-Namen als öffentlichem Namen zu spenden.

Dein Plugin ordnet donorName dann dem Spieler zu (ohne Groß-/Kleinschreibung). Passt zum Spendenzeitpunkt niemand, halte die Belohnung offen und vergib sie bei der nächsten Verbindung.

Geplant: ein „Einlöse-Code“-Ablauf (/claim <code> im Spiel) macht die Zuordnung zu 100 % zuverlässig, unabhängig vom Namen.

Bereit, deinen Server zu verbinden?

Erstelle einen API-Schlüssel im Dashboard deiner Kampagne und folge den Beispielen oben.

Mein Dashboard öffnen →