Echtzeit-Events für deine App

1. Erste Schritte

1. Melde dich auf devquake.com an und öffne Pulse aus deinem Konto (24 Stunden kostenlos testen oder abonnieren).
2. Lege einen API-Dienst an. Kopiere den geheimen Schlüssel sofort: Er wird nur einmal angezeigt.
3. Füge unter Deine Websites deine Seite und ihren DNS-Eintrag hinzu (oder schalte localhost erlauben ein, um auf deinem Computer zu testen).
4. Öffne den Live-Test und sende dein erstes Event.

2. Wofür man es nutzt

Für alles, bei dem sich eine Seite sofort ändern soll, wenn anderswo etwas passiert, ohne neu zu laden:

• Benachrichtigungen: „Deine Bestellung ist unterwegs“, „Neue Nachricht“, ein Zähler, der hochzählt.
• Live-Dashboards: Verkäufe, Anmeldungen, Sensorwerte oder Serverstatus in dem Moment, in dem sie passieren.
• Chat und Kommentare: Nachrichten, die bei allen im Raum erscheinen.
• Spielstände und Spiele: Live-Ergebnisse, Züge, eine Anzeigetafel auf dem Fernseher und den Handys zugleich.
• Zusammenarbeit: eine gemeinsame Liste oder Tafel, auf der alle die Änderungen der anderen sehen.
• Status eines Vorgangs: „wird verarbeitet … fertig“ bei Uploads, Zahlungen oder Exporten.
• Anwesenheit: wer gerade online ist oder tippt.

3. Das Event-Format

Jedes Event hat denselben festen Rahmen und darin deine eigenen Daten als Schlüssel und Werte:

• channel: wohin es geht, z. B. orders oder room-42. Empfänger wählen die Kanäle, die sie wollen.
• event: was passiert ist, z. B. order.created.
• data: deine Schlüssel und Werte, z. B. orderId: "A-17", total: 42.5, paid: true. Werte sind Text, Zahlen, Ja/Nein (true/false) oder leer (null).
• Pulse ergänzt id, app (deinen öffentlichen Schlüssel), source (Server, Webseite, Client-Token oder Live-Test), sender (aus einem Client-Token) und at (die Zeit, UTC).

Kanäle, deren Name mit private- beginnt, lassen sich nur mit einem Client-Token oder dem geheimen Schlüssel nutzen, nie mit dem öffentlichen Schlüssel allein.

4. Schlüssel und Sicherheit

• Öffentlicher Schlüssel (pk_…): kommt in deine Webseiten. Er funktioniert nur auf deinen bestätigten Websites, kann nur öffentliche Kanäle empfangen und, wenn du es erlaubst, an sie senden.
• Geheimer Schlüssel (sk_…): bleibt auf deinem Server. Er darf an jeden Kanal senden und Client-Tokens erstellen. Pulse lehnt ihn ab, wenn er aus einer Webseite kommt, denn ein Geheimnis im Browser ist keines mehr.
• Client-Tokens: Dein Server erstellt eines für jeden deiner Nutzer, höchstens eine Stunde gültig, mit den Kanälen, die dieser Nutzer verwenden darf, und ob er senden darf. So nutzt du private Kanäle und angemeldete Nutzer sicher.
• Nur du: Ein API-Dienst gehört allein deinem DevQuake-Konto. Er lässt sich nicht mit anderen Mitgliedern teilen.
• Serveradressen: Erlaube den geheimen Schlüssel optional nur von den IP-Adressen deiner Server.
• Lecks erkennen: Pulse zählt die Adressen, von denen dein geheimer Schlüssel benutzt wird, und protokolliert abgelehnte Aufrufe. Taucht der Schlüssel an zu vielen Orten auf, wirst du gewarnt: Erstelle einen neuen (der alte funktioniert noch 24 Stunden).

Warum ein kopierter Schlüssel niemandem hilft: Der öffentliche Schlüssel funktioniert nur auf Websites, die per DNS bewiesen haben, dass sie dir gehören; der geheime Schlüssel wird in Webseiten abgelehnt und kann an deine Server gebunden werden; und jeder Dienst hat Grenzen, sodass selbst ein gestohlener Schlüssel nicht mehr kann, als dein Tarif erlaubt.

5. Deine Website bestätigen

1. Gib unter Deine Websites die Adresse ein, z. B. https://shop.example.com.
2. Pulse zeigt einen TXT-Eintrag: einen Namen wie _devquake-pulse.shop.example.com und einen Wert wie devquake-pulse=….
3. Lege ihn dort an, wo du das DNS deiner Domain verwaltest (bei deinem Hosting- oder Domainanbieter).
4. Tippe auf Jetzt prüfen. Nach einigen Minuten (manchmal einer Stunde) zeigt die Website Bestätigt und funktioniert.

Zum Testen auf deinem eigenen Computer schalte localhost erlauben ein: Seiten auf http://localhost funktionieren dann ohne DNS-Eintrag. Schalte es ab, wenn du live gehst.

6. Deine eigene Datenstruktur

Unter Deine Datenstruktur beschreibst du jedes Event, das du nutzt: seine Schlüssel, ihren Typ (Text, Zahl oder Ja/Nein) und welche Pflicht sind. Zum Beispiel order.created mit orderId (Text, Pflicht), total (Zahl) und paid (Ja/Nein).

• Beschriebene Events werden geprüft: Ein fehlender Pflichtschlüssel oder ein falscher Typ wird mit einer klaren Fehlermeldung abgelehnt.
• Nicht beschriebene Events werden weiter angenommen, es sei denn, du schaltest Nur beschriebene Events ein.
• Mit Nur beschriebene Events werden auch unbekannte Events und Schlüssel abgelehnt: empfohlen für den Produktivbetrieb.

Schlüssel beginnen mit einem Buchstaben oder _ und enthalten Buchstaben, Ziffern und _. Höchstens 20 Schlüssel pro Event; Textwerte bis 500 Zeichen.

7. Live-Test-Szenario (5 Minuten)

Du brauchst: deinen API-Dienst, einen Computer mit Terminal und ein Handy (oder ein zweites Browserfenster). Eine Website brauchst du noch nicht.

1. Öffne deinen API-Dienst und tippe auf Live-Test. Behalte den Kanal demo und tippe auf Verbinden: Der Punkt wird grün, Live.
2. Öffne dieselbe Seite auf deinem Handy (bei DevQuake angemeldet) und tippe auch dort auf Verbinden.
3. Behalte am Computer unter Senden das Event hello mit dem Schlüssel text = Hello und tippe auf Event senden. Das Handy zeigt es innerhalb einer Sekunde, mit der benötigten Zeit.
4. Sende vom Handy: Der Computer empfängt es. Beide hören auf demo.
5. Führe in einem Terminal das curl-Beispiel der Seite aus, mit deinem geheimen Schlüssel statt $PULSE_SECRET_KEY. Beide Seiten empfangen ein Event von einem Server.
6. Teste die Regeln: Beschreibe unter Deine Datenstruktur ein Event, schalte Nur beschriebene Events ein und sende eines mit falschem Typ: Es wird mit Begründung abgelehnt.
7. Teste private Kanäle: Trenne die Verbindung, schalte Ein Client-Token nutzen ein, setze die Kanäle auf private-demo, verbinde beide Geräte und sende erneut.

Im kostenlosen Test kommen Events 3 Sekunden später an, und Verbindungen sind kürzer: Das ist Absicht. Zeigt eine Seite „Verbunden (Abfragen)“, sind Live-Verbindungen in diesem Netz blockiert; Events kommen trotzdem an, alle paar Sekunden.

8. Die API in Kürze

• POST /api/v1/events: ein Event senden. Inhalt: { "channel", "event", "data" }. Anmeldung: Authorization: Bearer sk_… (Server), Authorization: Bearer <Client-Token> oder X-Pulse-Key: pk_… (Webseite auf einer bestätigten Website). Antwort 202 { id, at }.
• GET /api/v1/stream?key=pk_…&channels=a,b: Live-Events (Server-Sent Events). Nutze token= statt key= für ein Client-Token. Neu verbundene Clients holen ab ihrem letzten Event nach (Last-Event-ID).
• GET /api/v1/poll?key=…&channels=…&after=<id>: dieselben Events durch Nachfragen alle paar Sekunden, für Orte, an denen Live-Verbindungen nicht funktionieren. Antwort { events, next, retryAfterMs }.
• GET /api/v1/client: eine kleine Browser-Bibliothek, die sich verbindet, neu verbindet, Tokens erneuert und von selbst auf Abfragen ausweicht.
• Fehler kommen als { "error": { "code", "message" } } mit dem HTTP-Status (401 Schlüssel, 403 nicht erlaubt, 402 kein Abo, 429 zu viele, mit Retry-After).

9. Test, Abo und voller Zugang

Pulse läuft neben allen anderen DevQuake-Apps, daher hat jedes Konto faire Grenzen. Dein aktueller Tarif und seine Zahlen stehen auf der Startseite der App.

• Kostenloser Test (24 Stunden): 1 API-Dienst, 3 Live-Verbindungen, 300 Events pro Tag, kleine Events, und Events kommen 3 Sekunden später an.
• Abonniert: 3 API-Dienste mit je 25 Live-Verbindungen und 10.000 Events pro Tag, Events sofort.
• Voller Zugang: viel höhere Grenzen für den Produktivbetrieb. Schreib uns und erzähl uns, was du baust.

Endet dein Abo, antworten deine API-Dienste nicht mehr (deine Apps bekommen „Abo erforderlich“). Kündigst du oder löschst du dein Konto, werden sie mit allen Daten gelöscht.

10. Deine Daten

Events werden nur so lange aufbewahrt, wie neu verbundene Clients zum Nachholen brauchen (höchstens einen Tag, mit vollem Zugang eine Woche), Nutzungszahlen 35 Tage und das Sicherheitsprotokoll 30 Tage. Geheime Schlüssel werden nie gespeichert, Adressen nur als anonyme Hashes. Das Löschen eines API-Dienstes, eine Kündigung oder das Löschen deines DevQuake-Kontos entfernt alles.

11. Live ausprobieren

Du willst Pulse in Aktion sehen, bevor du Code schreibst? Die Demo Live ausprobieren (auf der Startseite der App) sendet Events zwischen zwei deiner Browser über die echte API.

1. Öffne Live ausprobieren und drücke Link kopieren.
2. Öffne den Link in einem zweiten Browser (ein anderer Browser, ein privates Fenster oder dein Handy) und melde dich mit demselben DevQuake-Konto an.
3. Wähle Eine Nachricht und tippe etwas, oder Dein eigenes JSON und füge ein flaches Objekt ein, etwa { "order": 42, "paid": true }.
4. Drücke An meinen anderen Browser senden. Der andere Browser zeigt, was angekommen ist und wie lange es gedauert hat: Absender bis Server, Server bis Browser und insgesamt, mit Durchschnitt, schnellstem und langsamstem Wert.

Der Rahmen des Events (Kanal, Event-Name und die Stempel demo_from und demo_sent_at) ist fest; dein Inhalt kommt in data. Die Demo nutzt einen eigenen privaten Kanal, ist in jedem Tarif kostenlos, zählt nicht zu deinen Limits, erlaubt 30 Events pro Minute und löscht Demo-Events nach einer Stunde.

Code-Beispiele

Ersetze den Beispielschlüssel durch deinen öffentlichen Schlüssel (dein API-Dienst zeigt diese Beispiele mit deinem Schlüssel).

<script src="https://pulse.devquake.com/api/v1/client"></script>
<script>
  var pulse = DevQuakePulse.connect({
    key: 'pk_YourPublicKeyFromTheApp00',
    channels: ['demo'],
    onEvent: function (e) { console.log(e.event, e.data); },
    onStatus: function (s) { console.log('pulse:', s); }
  });
  // Only when "Browsers may send events" is on:
  // pulse.send('demo', 'hello', { text: 'Hi' });
</script>

curl -X POST https://pulse.devquake.com/api/v1/events \
  -H "Authorization: Bearer $PULSE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel":"demo","event":"hello","data":{"text":"Hi","count":1}}'

// Your server (Node.js): a client token for one of your users, valid for one hour.
import { createHmac } from 'node:crypto';

const b64 = (o) => Buffer.from(JSON.stringify(o)).toString('base64url');

export function pulseToken(userId, channels, canSend) {
  const now = Math.floor(Date.now() / 1000);
  const head = b64({ alg: 'HS256', typ: 'JWT' }) + '.' + b64({
    app: 'pk_YourPublicKeyFromTheApp00', ch: channels, pub: canSend,
    sub: String(userId), iat: now, exp: now + 3600,
  });
  const sig = createHmac('sha256', process.env.PULSE_SECRET_KEY).update(head).digest('base64url');
  return head + '.' + sig;
}

// In the page: DevQuakePulse.connect({ token: () => fetch("/my/pulse-token").then((r) => r.text()), … })

{
  "id": "812",
  "app": "pk_YourPublicKeyFromTheApp00",
  "channel": "orders",
  "event": "order.created",
  "data": {
    "orderId": "A-17",
    "total": 42.5,
    "paid": true
  },
  "source": "server",
  "at": "2026-09-26T10:00:00.000Z"
}