Valós idejű események az alkalmazásodhoz

1. Első lépések

1. Jelentkezz be a(z) devquake.com oldalon, és nyisd meg a Pulse-t a fiókodból (próbáld ki 24 órán át ingyen, vagy fizess elő).
2. Hozz létre egy API-szolgáltatást. Azonnal másold ki a titkos kulcsot: csak egyszer látható.
3. A Weboldalaid alatt add hozzá az oldaladat és a DNS-rekordját (vagy kapcsold be a localhost engedélyezése beállítást a gépeden való teszteléshez).
4. Nyisd meg az Élő tesztet, és küldd el az első eseményedet.

2. Mire használják

Mindenre, ahol egy oldalnak azonnal változnia kell, amikor máshol történik valami, újratöltés nélkül:

• Értesítések: „A rendelésed úton van”, „Új üzenet”, egy felfelé számláló jelvény.
• Élő irányítópultok: eladások, regisztrációk, szenzoradatok vagy a szerverek állapota abban a pillanatban.
• Cset és hozzászólások: üzenetek, amelyek a szobában mindenkinél megjelennek.
• Eredmények és játékok: élő eredmények, körök, eredményjelző egyszerre a tévén és a telefonokon.
• Együttműködés: közös lista vagy tábla, ahol mindenki látja a többiek változtatásait.
• Folyamatok állapota: „feldolgozás… kész” feltöltéseknél, fizetéseknél vagy exportoknál.
• Jelenlét: ki van éppen online vagy ki gépel.

3. Az esemény formátuma

Minden eseménynek ugyanaz a rögzített kerete, benne pedig a saját adataid kulcsok és értékek formájában:

• channel: hová megy, pl. orders vagy room-42. A fogadók kiválasztják a kívánt csatornákat.
• event: mi történt, pl. order.created.
• data: a kulcsaid és értékeid, pl. orderId: "A-17", total: 42.5, paid: true. Az értékek szövegek, számok, igen/nem (true/false) vagy üresek (null).
• A Pulse hozzáadja: id, app (a nyilvános kulcsod), source (szerver, weboldal, kliens-token vagy élő teszt), sender (kliens-tokenből) és at (az idő, UTC).

A private- kezdetű csatornák csak kliens-tokennel vagy a titkos kulccsal használhatók, a nyilvános kulccsal önmagában soha.

4. Kulcsok és biztonság

• Nyilvános kulcs (pk_…): a weboldalaidba kerül. Csak az igazolt weboldalaidon működik, csak nyilvános csatornákat fogadhat, és ha engeded, küldhet is rájuk.
• Titkos kulcs (sk_…): a szervereden marad. Bármely csatornára küldhet, és kliens-tokeneket készíthet. A Pulse elutasítja, ha weboldalról érkezik, mert a böngészőben lévő titok már nem titok.
• Kliens-tokenek: a szervered minden felhasználódnak készít egyet, legfeljebb egy óráig érvényeset, benne azokkal a csatornákkal, amelyeket használhat, és hogy küldhet-e. Ez a biztonságos út a privát csatornákhoz és a bejelentkezett felhasználókhoz.
• Csak te: egy API-szolgáltatás kizárólag a DevQuake-fiókodhoz tartozik. Nem osztható meg más tagokkal.
• Szervercímek: ha szeretnéd, a titkos kulcsot csak a szervereid IP-címeiről engedélyezheted.
• Szivárgás figyelése: a Pulse számolja, hány címről használják a titkos kulcsodat, és naplózza az elutasított hívásokat. Ha a kulcs túl sok helyen bukkan fel, figyelmeztetünk: készíts újat (a régi még 24 óráig működik).

Miért nem segít senkinek egy lemásolt kulcs: a nyilvános kulcs csak olyan weboldalakon működik, amelyek DNS-sel igazolták, hogy a tieid; a titkos kulcsot weboldalakban elutasítjuk, és a szervereidhez köthető; és minden szolgáltatásnak kerete van, így még egy ellopott kulcs sem tud többet, mint amit a csomagod enged.

5. A weboldalad igazolása

1. A Weboldalaid alatt add meg a címet, pl. https://shop.example.com.
2. A Pulse megmutat egy TXT-rekordot: egy nevet, például _devquake-pulse.shop.example.com, és egy értéket, például devquake-pulse=….
3. Add hozzá ott, ahol a domained DNS-ét kezeled (a tárhely- vagy domainszolgáltatódnál).
4. Nyomd meg az Ellenőrzés most gombot. Néhány perc (néha egy óra) után a weboldal Igazolva állapotú lesz, és működik.

A saját gépeden való teszteléshez kapcsold be a localhost engedélyezése beállítást: a http://localhost oldalak így DNS-rekord nélkül is működnek. Kapcsold ki, amikor élesbe mész.

6. Saját adatszerkezet

A Saját adatszerkezeted alatt leírod az általad használt eseményeket: a kulcsaikat, a típusukat (szöveg, szám vagy igen/nem), és hogy melyik kötelező. Például order.created ezekkel: orderId (szöveg, kötelező), total (szám) és paid (igen/nem).

• A leírt eseményeket ellenőrizzük: a hiányzó kötelező kulcsot vagy a rossz típust világos hibaüzenettel elutasítjuk.
• A nem leírt eseményeket továbbra is elfogadjuk, hacsak be nem kapcsolod a Csak leírt események beállítást.
• Bekapcsolt Csak leírt események mellett az ismeretlen eseményeket és kulcsokat is elutasítjuk: éles használatra ajánlott.

A kulcsok betűvel vagy _ jellel kezdődnek, és betűket, számjegyeket és _ jelet tartalmaznak. Eseményenként legfeljebb 20 kulcs; a szöveges értékek legfeljebb 500 karakteresek.

7. Élő teszt forgatókönyv (5 perc)

Amire szükséged van: az API-szolgáltatásod, egy gép terminállal és egy telefon (vagy egy második böngészőablak). Weboldal még nem kell.

1. Nyisd meg az API-szolgáltatásodat, és nyomd meg az Élő teszt gombot. Hagyd a demo csatornát, és nyomd meg a Csatlakozás gombot: a pont zöld lesz, Élő.
2. Nyisd meg ugyanezt az oldalt a telefonodon (DevQuake-be bejelentkezve), és ott is nyomd meg a Csatlakozás gombot.
3. A gépen a Küldés alatt hagyd a hello eseményt a text = Hello kulccsal, és nyomd meg az Esemény küldése gombot. A telefon egy másodpercen belül megjeleníti, az eltelt idővel.
4. Küldj a telefonról: a gép megkapja. Mindkettő a demo csatornát figyeli.
5. Egy terminálban futtasd az oldal curl példáját, a $PULSE_SECRET_KEY helyett a titkos kulcsoddal. Mindkét oldal megkapja a szerverről jövő eseményt.
6. Próbáld ki a szabályokat: írj le egy eseményt a Saját adatszerkezeted alatt, kapcsold be a Csak leírt események beállítást, és küldj egyet rossz típussal: indoklással elutasítjuk.
7. Próbáld ki a privát csatornákat: válaszd le, kapcsold be a Kliens-token használata beállítást, állítsd a csatornát private-demo-ra, csatlakoztasd mindkét eszközt, és küldj újra.

Az ingyenes próba alatt az események 3 másodperc késéssel érkeznek, és a kapcsolatok rövidebbek: ez szándékos. Ha egy oldal „Csatlakozva (lekérdezés)” állapotot mutat, azon a hálózaton az élő kapcsolatok tiltottak; az események így is megérkeznek, néhány másodpercenként.

8. Az API röviden

• POST /api/v1/events: egy esemény küldése. Tartalom: { "channel", "event", "data" }. Hitelesítés: Authorization: Bearer sk_… (szerver), Authorization: Bearer <kliens-token> vagy X-Pulse-Key: pk_… (weboldal egy igazolt oldalon). Válasz: 202 { id, at }.
• GET /api/v1/stream?key=pk_…&channels=a,b: élő események (Server-Sent Events). Kliens-tokenhez key= helyett token=. Az újracsatlakozó kliensek az utolsó eseményüktől pótolnak (Last-Event-ID).
• GET /api/v1/poll?key=…&channels=…&after=<id>: ugyanazok az események néhány másodpercenkénti lekérdezéssel, ahol az élő kapcsolat nem működik. Válasz: { events, next, retryAfterMs }.
• GET /api/v1/client: kis böngészős könyvtár, amely csatlakozik, újracsatlakozik, megújítja a tokeneket, és magától lekérdezésre vált.
• A hibák { "error": { "code", "message" } } formában érkeznek a HTTP-státusszal (401 kulcs, 403 nem engedélyezett, 402 nincs előfizetés, 429 túl sok, Retry-After fejléccel).

9. Próba, előfizetés és teljes hozzáférés

A Pulse az összes többi DevQuake-alkalmazás mellett fut, ezért minden fióknak igazságos keretei vannak. Az aktuális csomagod és a számai az alkalmazás kezdőlapján láthatók.

• Ingyenes próba (24 óra): 1 API-szolgáltatás, 3 élő kapcsolat, napi 300 esemény, kis események, 3 másodperc késéssel.
• Előfizetve: 3 API-szolgáltatás, mindegyik 25 élő kapcsolattal és napi 10 000 eseménnyel, azonnali kézbesítéssel.
• Teljes hozzáférés: sokkal magasabb keretek éles használatra. Írj nekünk, és mondd el, mit építesz.

Ha lejár az előfizetésed, az API-szolgáltatásaid nem válaszolnak (az alkalmazásaid „előfizetés szükséges” választ kapnak). Ha leiratkozol vagy törlöd a fiókodat, minden adatukkal együtt törlődnek.

10. Az adataid

Az eseményeket csak addig őrizzük, amíg az újracsatlakozó klienseknek pótolniuk kell (legfeljebb egy napig, teljes hozzáféréssel egy hétig), a használati adatokat 35 napig, a biztonsági naplót 30 napig. A titkos kulcsokat soha nem tároljuk, a címeket csak névtelen hash-ként. Egy API-szolgáltatás törlése, a leiratkozás vagy a DevQuake-fiók törlése mindent eltávolít.

11. Próbáld ki élőben

Szeretnéd működés közben látni a Pulse-t, mielőtt kódot írsz? A Próbáld ki élőben demó (az alkalmazás kezdőlapján) két böngésződ között küld eseményeket a valódi API-n keresztül.

1. Nyisd meg a Próbáld ki élőben oldalt, és nyomd meg a Link másolása gombot.
2. Nyisd meg a linket egy második böngészőben (másik böngésző, privát ablak vagy a telefonod), és jelentkezz be ugyanazzal a DevQuake-fiókkal.
3. Válaszd az Üzenet lehetőséget és írj valamit, vagy a Saját JSON lehetőséget és illessz be egy lapos objektumot, például { "order": 42, "paid": true }.
4. Nyomd meg a Küldés a másik böngészőmbe gombot. A másik böngésző mutatja, mi érkezett és mennyi ideig tartott: küldőtől a szerverig, szervertől a böngészőig és összesen, átlaggal, a leggyorsabbal és a leglassabbal.

Az esemény kerete (csatorna, eseménynév, valamint a demo_from és demo_sent_at bélyeg) rögzített; a tartalmad a data részbe kerül. A demó egy csak a tiéd privát csatornát használ, minden csomagban ingyenes, nem számít bele a korlátaidba, percenként 30 eseményt enged, és egy óra után törli a demóeseményeket.

Kódpéldák

Cseréld a példakulcsot a saját nyilvános kulcsodra (az API-szolgáltatásod ezeket a példákat a kulcsoddal kitöltve mutatja).

<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"
}