Evenimente în timp real pentru aplicația ta

1. Primii pași

1. Autentifică-te pe devquake.com și deschide Pulse din contul tău (încearcă-l gratuit 24 de ore sau abonează-te).
2. Creează un serviciu API. Copiază imediat cheia secretă: este afișată o singură dată.
3. La Site-urile tale, adaugă site-ul și înregistrarea lui DNS (sau pornește Permite localhost ca să testezi pe calculator).
4. Deschide Testul live și trimite primul eveniment.

2. La ce se folosește

Pentru orice situație în care o pagină trebuie să se schimbe imediat ce se întâmplă ceva în altă parte, fără reîncărcare:

• Notificări: „Comanda ta a fost expediată”, „Mesaj nou”, un contor care crește.
• Panouri live: vânzări, înscrieri, citiri de senzori sau starea serverelor pe loc.
• Chat și comentarii: mesaje care apar pentru toți cei din cameră.
• Scoruri și jocuri: rezultate live, ture, un tabel de scor pe televizor și pe telefoane deodată.
• Colaborare: o listă sau o tablă comună unde fiecare vede modificările celorlalți.
• Starea unei operațiuni: „se procesează… gata” pentru încărcări, plăți sau exporturi.
• Prezență: cine e online sau scrie acum.

3. Formatul evenimentului

Fiecare eveniment are același cadru fix și, în interior, propriile tale date ca chei și valori:

• channel: unde merge, de ex. orders sau room-42. Ascultătorii aleg canalele dorite.
• event: ce s-a întâmplat, de ex. order.created.
• data: cheile și valorile tale, de ex. orderId: "A-17", total: 42.5, paid: true. Valorile sunt text, numere, da/nu (true/false) sau goale (null).
• Pulse adaugă id, app (cheia ta publică), source (server, pagină web, token de client sau test live), sender (dintr-un token de client) și at (ora, UTC).

Canalele al căror nume începe cu private- pot fi folosite doar cu un token de client sau cu cheia secretă, niciodată doar cu cheia publică.

4. Chei și securitate

• Cheia publică (pk_…): intră în paginile tale web. Funcționează doar pe site-urile tale verificate, poate asculta doar canale publice și, dacă permiți, poate trimite pe ele.
• Cheia secretă (sk_…): rămâne pe serverul tău. Poate trimite pe orice canal și poate crea tokenuri de client. Pulse o refuză când vine dintr-o pagină web, pentru că un secret în browser nu mai e secret.
• Tokenuri de client: serverul tău creează câte unul pentru fiecare utilizator, valabil cel mult o oră, cu canalele pe care le poate folosi și dacă poate trimite. Acesta e modul sigur pentru canale private și utilizatori autentificați.
• Doar tu: un serviciu API aparține doar contului tău DevQuake. Nu poate fi partajat cu alți membri.
• Adresele serverului: opțional, permite cheia secretă doar de pe adresele IP ale serverelor tale.
• Detectarea scurgerilor: Pulse numără adresele de pe care e folosită cheia secretă și înregistrează apelurile refuzate. Dacă cheia apare în prea multe locuri, ești avertizat: creează una nouă (cea veche mai merge 24 de ore).

De ce o cheie copiată nu ajută pe nimeni: cheia publică funcționează doar pe site-uri care au dovedit prin DNS că sunt ale tale; cheia secretă e refuzată în pagini web și poate fi legată de serverele tale; iar fiecare serviciu are limite, deci nici o cheie furată nu poate face mai mult decât permite planul tău.

5. Verificarea site-ului tău

1. La Site-urile tale, introdu adresa, de ex. https://shop.example.com.
2. Pulse afișează o înregistrare TXT: un nume ca _devquake-pulse.shop.example.com și o valoare ca devquake-pulse=….
3. Adaug-o acolo unde gestionezi DNS-ul domeniului (la furnizorul de găzduire sau de domeniu).
4. Apasă Verifică acum. După câteva minute (uneori o oră), site-ul apare ca Verificat și funcționează.

Ca să testezi pe propriul calculator, pornește Permite localhost: paginile de pe http://localhost funcționează atunci fără înregistrare DNS. Oprește opțiunea când treci în producție.

6. Propria structură de date

La Structura datelor tale descrii fiecare eveniment folosit: cheile, tipul lor (text, număr sau da/nu) și care sunt obligatorii. De exemplu order.created cu orderId (text, obligatoriu), total (număr) și paid (da/nu).

• Evenimentele descrise sunt verificate: o cheie obligatorie lipsă sau un tip greșit sunt refuzate cu o eroare clară.
• Evenimentele nedescrise sunt acceptate în continuare, dacă nu pornești Doar evenimente descrise.
• Cu Doar evenimente descrise pornit, sunt refuzate și evenimentele și cheile necunoscute: recomandat în producție.

Cheile încep cu o literă sau _ și conțin litere, cifre și _. Cel mult 20 de chei per eveniment; valori text de până la 500 de caractere.

7. Scenariu de test live (5 minute)

Ai nevoie de: serviciul tău API, un calculator cu terminal și un telefon (sau o a doua fereastră de browser). Încă nu ai nevoie de un site.

1. Deschide serviciul API și apasă Test live. Păstrează canalul demo și apasă Conectează: punctul devine verde, Live.
2. Deschide aceeași pagină pe telefon (autentificat în DevQuake) și apasă și acolo Conectează.
3. Pe calculator, la Trimite, păstrează evenimentul hello cu cheia text = Hello și apasă Trimite evenimentul. Telefonul îl afișează într-o secundă, cu timpul necesar.
4. Trimite de pe telefon: calculatorul îl primește. Ambele ascultă demo.
5. Într-un terminal, rulează exemplul curl din pagină cu cheia ta secretă în locul lui $PULSE_SECRET_KEY. Ambele pagini primesc un eveniment de la un server.
6. Testează regulile: descrie un eveniment la Structura datelor tale, pornește Doar evenimente descrise și trimite unul cu tip greșit: e refuzat cu motivul.
7. Testează canalele private: deconectează-te, pornește Folosește un token de client, setează canalele la private-demo, conectează ambele dispozitive și trimite din nou.

În perioada de probă, evenimentele ajung cu 3 secunde întârziere și conexiunile sunt mai scurte: e intenționat. Dacă o pagină arată „Conectat (interogare)”, conexiunile live sunt blocate în acea rețea; evenimentele ajung totuși, la câteva secunde.

8. API-ul pe scurt

• POST /api/v1/events: trimite un eveniment. Conținut: { "channel", "event", "data" }. Autentificare: Authorization: Bearer sk_… (server), Authorization: Bearer <token de client> sau X-Pulse-Key: pk_… (pagină pe un site verificat). Răspuns 202 { id, at }.
• GET /api/v1/stream?key=pk_…&channels=a,b: evenimente live (Server-Sent Events). Folosește token= în loc de key= pentru un token de client. Clienții reconectați recuperează de la ultimul eveniment (Last-Event-ID).
• GET /api/v1/poll?key=…&channels=…&after=<id>: aceleași evenimente prin interogări la câteva secunde, unde conexiunile live nu funcționează. Răspuns { events, next, retryAfterMs }.
• GET /api/v1/client: o mică bibliotecă pentru browser care se conectează, se reconectează, reînnoiește tokenurile și trece singură la interogări.
• Erorile vin ca { "error": { "code", "message" } } cu statusul HTTP (401 cheie, 403 nepermis, 402 fără abonament, 429 prea multe, cu Retry-After).

9. Probă, abonament și acces complet

Pulse rulează alături de toate celelalte aplicații DevQuake, așa că fiecare cont are limite corecte. Planul tău actual și cifrele lui apar pe pagina de start a aplicației.

• Probă gratuită (24 de ore): 1 serviciu API, 3 conexiuni live, 300 de evenimente pe zi, evenimente mici, care ajung cu 3 secunde întârziere.
• Abonat: 3 servicii API, fiecare cu 25 de conexiuni live și 10.000 de evenimente pe zi, evenimente imediat.
• Acces complet: limite mult mai mari pentru producție. Scrie-ne și spune-ne ce construiești.

Când se termină abonamentul, serviciile tale API nu mai răspund (aplicațiile tale primesc „abonament necesar”). Când te dezabonezi sau îți ștergi contul, ele sunt șterse cu toate datele.

10. Datele tale

Evenimentele se păstrează doar cât e nevoie ca clienții reconectați să recupereze (cel mult o zi, o săptămână cu acces complet), cifrele de utilizare 35 de zile și jurnalul de securitate 30 de zile. Cheile secrete nu sunt stocate niciodată, iar adresele doar ca hash-uri anonime. Ștergerea unui serviciu API, dezabonarea sau ștergerea contului DevQuake elimină totul.

11. Încearcă live

Vrei să vezi Pulse în acțiune înainte să scrii cod? Demo-ul Încearcă live (pe pagina de start a aplicației) trimite evenimente între două dintre browserele tale prin API-ul real.

1. Deschide Încearcă live și apasă Copiază linkul.
2. Deschide linkul într-un al doilea browser (alt browser, o fereastră privată sau telefonul) și autentifică-te cu același cont DevQuake.
3. Alege Un mesaj și scrie ceva, sau Propriul JSON și lipește un obiect plat, de exemplu { "order": 42, "paid": true }.
4. Apasă Trimite la celălalt browser. Celălalt browser arată ce a sosit și cât a durat: de la expeditor la server, de la server la browser și în total, cu media, cel mai rapid și cel mai lent.

Cadrul evenimentului (canalul, numele evenimentului și ștampilele demo_from și demo_sent_at) este fix; conținutul tău intră în data. Demo-ul folosește un canal privat doar al tău, este gratuit în orice plan, nu se socotește în limitele tale, permite 30 de evenimente pe minut și șterge evenimentele demo după o oră.

Exemple de cod

Înlocuiește cheia de exemplu cu cheia ta publică (serviciul tău API arată aceste exemple cu cheia ta completată).

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