Skava Skava / Wiki

Pripojenie vlastných prvkov pre vývojárov

Táto stránka je určená vývojárom, ktorí pripájajú backend firmy k Skave. Vytvorenie a zverejnenie API prvku je popísané na stránke Vlastné prvky: rozhrania API; tu sa zameriavame na všetko, čo sa musí odohrať na druhej strane spojenia.

Myšlienka v jednej vete: Skava nezná vašu doménu. Pozná presne jeden formát, a to kartu. Vy rozhodujete, čo bude obsahovať, my kontrolujeme len tvar, veľkosť a bezpečnosť. Objednávka materiálu je len jeden príklad; ďalšia firma zbiera spätnú väzbu od používateľov, tá ďalšia archivuje fotku staviska vo vlastných záznamoch.

Prehľad toku na prvý pohľad

  1. Administrátor firmy vytvorí v Skave API prvok: formulár plus adresa, metóda a token vášho backendu.
  2. Niekto v čate vyplní formulár a pošle ho.
  3. Skava zavolá váš backend a pošle vyplnené hodnoty ako JSON.
  4. Vaša odpoveď sa stane kartou v čate.
  5. Voliteľne neskôr hlásite nové stavy cez callback. Každé hlásenie sa stane ďalšou kartou; predchádzajúca zostane.

Požiadavky na váš backend

  • HTTPS. Používajte iba https://, bez http, bez prihlasovacích údajov v adrese, maximálne 2000 znakov.
  • Verejne dostupné. Hostiteľ musí riešiť výhradne na verejné IP adresy. Lokálne adresy, súkromné siete, link-local adresy a cloudové metadáta sa zamietajú a toto sa kontroluje pri každom volaní.
  • Fixná adresa. Skava vyrieši hostiteľa len raz a pripojenie viaže na túto IP adresu. Zmena DNS počas volania nemá žiadny vplyv.
  • Bez presmerovaní. Presmerovanie 301 na „správnu“ adresu sa počíta ako zlyhanie. Zadajte konečnú adresu hneď na začiatku.
  • Čas odozvy. Časový limit je nastavený pre každý prvok a má tvrdý strop 30 sekúnd. Ak potrebujete viac času, odpovedajte okamžite a výsledok nahláste neskôr cez spätné volanie.
  • Veľkosť odpovede. Skava číta najviac 256 KiB.
  • Content-Type. Telo sa spracúva iba pri application/json.

Požiadavka, ktorá k vám príde

Metóda je GET, POST, PUT alebo PATCH, v závislosti od prvku. Pri POST, PUT a PATCH prichádzajú hodnoty ako JSON telo, pri GET ako parametre dotazu.

Autentifikácia je jeden hlavičkový parameter, ktorého názov a predpona hodnoty sú nastavené v prvku, zvyčajne Authorization s predponou Bearer . Token je u nás uložený zašifrovaný. Hlavičky host, content-length, content-type, cookie a accept-encoding sa nedajú nastaviť.

Telo je rovný objekt. Kľúče si vyberie ten, kto prvok vytvoril; hniezdenie sa objaví len tam, kde pridal tabuľku alebo výber produktu:

{"artikelnummer": "5100110", "menge": 20, "note": "Please deliver in the morning", "orderer": "Jonas Berger", "company": "Sanitar Berger GmbH", "project": "Spitalstrasse 11", "locale": "de", "callback_url": "https://chat.skava.io/api/v1/custom-elements/interactions/…", "callback_token": "…"}

Tieto tri kľúče vždy pochádzajú od nás, preto ich nepoužívajte sami:

  • locale: jazykový kód používateľa. Odpovedajte v tomto jazyku; vaše texty neprekladáme.
  • callback_url a callback_token: spätné volanie pre toto jedno interakcie, pozri nižšie. Sú prítomné len vtedy, keď volanie pochádza z chatu.

Kontextové polia, ako sú meno, firma, projekt alebo podchat, vyplní samotný server na základe kanála, v ktorom bol prvok spustený. Upravený klient tam nemôže tvrdiť iné meno projektu.

Odpoveď: formát karty

Odpovedzte s 2xx a objektom card. Presne toto sa stane kartou v čate:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Order received", "icon": "package", "fields": [{"label": "Order number", "value": "BST-10001"}, {"label": "Expected", "value": "14/08/2026"}]}}

  • v (povinné): celé číslo 1. Ako text ("1") sa zamietne. Bez neho sa odpoveď nepočíta ako karta a aplikuje sa mapovanie odpovede nastavené v prvku.
  • title: nadpis karty.
  • state: iba farba a tón ikony, jedna z hodnôt ok, pending, warn, error. Neznáma hodnota sa vráti na ok a dostanete upozornenie.
  • status_text: voľný text, ktorý neinterpretujeme. Nachádza sa v hornej časti karty a zobrazuje sa aj v zozname chatov a v push notifikácii.
  • fields: zoznam položiek label a value. Maximálne 20 záznamov, label 80 znakov, value 200, title a status_text po 120. Príliš dlhé hodnoty sa skracujú, neodmietajú: objednávka by nemala zlyhať kvôli detailu.
  • icon: pozri nižšie.

Čo Skava urobí s vašimi textami predtým, než sa dostanú do chatu: odstrihne sa preskakovanie riadkov a ovládacie znaky (znak pre čítanie zprava doľava by inak mohol otočiť zobrazenie sumy), backticks sa nahradia a všetko, čo začína na [SKAVA:, sa neutralizuje. Posledná vec bráni tomu, aby sa hodnota karty čítala ako iný chatový prvok, napríklad ako platobná žiadosť.

Odkazy v poliach, HTML a obrázky sa nedajú nastaviť. Chat je dôveryhodné prostredie a klikateľná adresa z cudzieho backendu by bola pozvánkou na prebudovanie prihlasovacej stránky.

Vstupy používateľa patria na server: zobrazujú sa na prvej karte a nemôžete ich prepísať. V čate predstavujú záznam o tom, čo bolo skutočne odoslané.

Ikony

Pomocou icon dostane karta vlastnú značku v hlavičke. Dve možnosti:

Názov z balíka: package, package-check, package-open, box, boxes, truck, forklift, warehouse, settings, cog, gauge, wrench, hammer, drill, hard-hat, ruler, paint-roller, construction, clipboard-check, receipt, file-text, camera, clock, calendar-clock, circle-check, circle-alert, triangle-alert, send, mail-check, shopping-cart, credit-card, map-pin.

Alebo vlastné SVG ako reťazec. Skava z neho vezme iba geometriu (path, circle, ellipse, rect, line, polyline, polygon s ich číselnými atribútmi) a vytvorí vlastný obrázok. Skripty, štýly, externé odkazy, foreignObject a atribúty udalostí sa zahodia; doctype alebo entita vedú k zamietnutiu; súbor môže mať maximálne 8 KiB a obsahovať maximálne 16 tvarov. Farbu, hrúbku čiary a veľkosť nastavuje Skava, takže ikona sa nemôže maskovať ako ovládacie prvok. Pracujte na mriežke 24 x 24.

Bez icon zostane predvolená značka.

Kallback: hlásenie neskôrších stavov

Volanie obsahuje callback_url a callback_token. Použite ich na neskoršie hlásenie nových stavov:

POST <callback_url> s hlavičkami Authorization: Bearer <callback_token> a Content-Type: application/json, telo požiadavky max. 32 KiB:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Shipped", "icon": "truck", "fields": [{"label": "Tracking number", "value": "DPD123456789"}]}, "seq": 3, "final": false}

Okrem karty existujú tri voliteľné hodnoty:

  • seq: vlastný počítadlo. Správa s menšou alebo rovnakou hodnotou sa zahodí, aby sa dve správy nemohli prebehnúť. Bez seq vyhrá tá, ktorá príde posledná.
  • final: ukončí interakciu. Token sa stane neplatným a už sa nezobrazia ďalšie karty. Povolené aj v prvej odpovedi, pre procesy bez ďalších krokov.
  • notify: nastavte na false, aby sa karta zobrazila ticho, bez počtu neprečítaných správ a bez notifikácie. Pre medzistavy, ktoré by nemali nikoho budiť. Bez tohto nastavenia je karta bežnou správou.

Každá správa sa stane vlastnou kartou v čate, predchádzajúca zostane. Tak je čitateľné, ktorý stav bol nahlásený. Z toho vyplýva odporúčanie: posielať len to, čo sa zmenilo. Karta, ktorá štvrtýkrát opakuje číslo objednávky, položky a celkovú sumu, je pre čitateľa len šum.

Dve obmedzenia: rovnaká správa dvakrát nevznikne druhá karta a interakcia môže odoslať najviac 50 kariet. Interakcia prijíma správy po dobu 90 dní.

Odpovede, na ktoré by ste mali reagovať

  • 200 s {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Prečítajte si nápovedy: uvádzajú, čo bolo skrátené alebo vynechané.
  • 401: nesprávny token alebo identifikátor interakcie. Neopakovujte požiadavku.
  • 410: interakcia bola uzavretá alebo vypršala. Neopakovujte požiadavku.
  • 422: karta je nepoužiteľná, dôvod je v hints. Najprv ho opravte.
  • 400 poškodené JSON, 413 príliš veľké, 429 príliš veľa požiadaviek (opakovajte s odstupom), 500 chyba na našej strane, skúste neskôr.

Príklad 1: objednávka s históriou stavov

Krok 1, požiadavka na váš backend:

POST https://api.example.com/v1/orders
Authorization: Bearer <your token>
{"artikelnummer": "5100110", "menge": 20, "orderer": "Jonas Berger", "company": "Sanitar Berger GmbH", "locale": "de", "callback_url": "https://chat.skava.io/api/v1/custom-elements/interactions/1111…", "callback_token": "secret"}

Krok 2, vaša okamžitá odpoveď:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Order received", "icon": "package", "fields": [{"label": "Order number", "value": "BST-10001"}, {"label": "Expected", "value": "14/08/2026"}]}}

Chat teraz zobrazuje kartu s ikonou balíka, stavom a vstupmi používateľa.

Krok 3, neskôr pri výbere:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Being picked", "icon": "cog", "fields": []}, "seq": 2, "notify": false}

Tichá druhá karta bez polí: zmenila sa iba stav.

Krok 4, pri odoslaní:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Shipped", "icon": "truck", "fields": [{"label": "Tracking number", "value": "DPD123456789"}, {"label": "Carrier", "value": "DPD"}]}, "seq": 3}

Táto karta môže niekoho prebudiť, preto nie je nastavené notify: false.

Krok 5, pri doručení:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "ok", "status_text": "Delivered", "icon": "package-check", "fields": []}, "seq": 4, "final": true}

S kľúčovým slovom final je interakcia uzavretá a token už nefunguje.

Príklad 2: akcia bez ďalších krokov

Nie každý priebeh má históriu. Prvok s jedným poľom, ktorý odovzdá niečo vášmu systému, potrebuje len jednu odpoveď:

{"card": {"v": 1, "title": "Filed", "state": "ok", "status_text": "Stored under project 4711", "icon": "clipboard-check", "fields": [{"label": "Case", "value": "4711"}]}, "final": true}

Tu je dôležité final: true: inak by interakcia zostala otvorená 90 dní s platným tokenom, hoci už nikdy nič neohlásite.

Výber produktu z katalógu

Ak spoločnosť nahrala svoj katalóg článkov, prvok môže obsahovať blok výberu produktov. Používateľ z neho zostaví košík a vy ho dostanete ako zoznam pod kľúčom, ktorý zvolil tvorca prvku:

{"items": [{"artikelnummer": "5100110", "menge": 20}, {"artikelnummer": "5100111", "menge": 2}], "note": "…"}

Keďže kľúč je voľný, hľadajte prvý zoznam s touto štruktúrou, nie pevné meno. Pred odoslaním Skava overí, či každé číslo skutočne existuje v katalógu danej spoločnosti, maximálne 50 položiek. V karte sa položky zobrazia ako zoznam s obrázkom produktu, názvom a množstvom.

Testovanie

  • Ping v editore prvku odosiela čistý požiadavku HEAD bez tokena a bez dát. Odpovedzte čokoľvek, akákoľvek HTTP odpoveď sa počíta ako dostupnosť.
  • Testovacia požiadavka spustí skutočné volanie s ukážkovými hodnotami, aj keď je prvok ešte v koncepte, a zobrazí požiadavku, odpoveď a správy validátora karty.
  • Náhľad v susednom paneli: vložte svoju odpoveď v JSON, skontrolujte ju a uvidíte dokončenú kartu spolu s nápovedou. Na serveri sa overuje rovnakým kódom ako v produkčnom prostredí.
  • Ukážkový server: kompletný ukážkový dodávateľ beží na api.skava.io a používa všetko, čo je vyššie opísané. Jeho zdrojový kód sa nachádza v repozitáriu v priečinku example_order_server/, má približne 600 riadkov čistého štandardného knižničného kódu a je určený na kopírovanie.

Čo ešte treba vedieť

  • Karta je úplne bežnou chatovou správou. Zobrazí sa vo vyhľadávaní, dá sa citovať a zostáva v histórii.
  • Posiela ju systémový odosielateľ, nie účet vašej firmy. Napriek tomu sa zobrazuje na strane toho, kto prvok spustil, a v nadpise je uvedené, ktorý systém píše.
  • Kto ho môže spúšťať, je nastavené na prvku: iba členovia firmy, alebo aj vonkajší používatelia, ktorí s ním zdieľajú chat. Keď vaša firma chat opustí, oprávnenie sa skončí automaticky.
  • API prvok s vypršaným tokenom je v spánku: aktuálne aplikácie ho skryjú v menu a volanie, ktoré sa napriek tomu pošle, sa na serveri odmietne. Administrátor pre neho uloží nový token, čo funguje aj na uvoľnenom rozhraní.

Súvisiace

Vytváranie a uvoľňovanie: Vlastné prvky: API rozhrania. Vyplniteľné dokumenty namiesto rozhraní: Vlastné prvky: Dokumenty.