Skava Skava / Wiki

Custom Elements csatlakoztatása fejlesztőknek

Ez az oldal azoknak szól, akik egy vállalat háttérrendszerét kötik össze a Skavával. Az API elem létrehozásának és kiadásának folyamatát a Custom Elements: API felületek oldalon találod meg; itt mindent lefedünk, ami a vonal másik végén történik.

Az ötlet egy mondatban: a Skava nem ismeri a te üzleti területedet. Pontosan egy formátumot ismer, a kártyát. Te döntöd el, mit írjon, mi pedig csak az alakot, a méretet és a biztonságot ellenőrizzük. Egy anyagmegrendelés például csak egy példa; a következő cég felhasználói visszajelzéseket gyűjt, az utána következő pedig a saját nyilvántartásába tárolja a helyszíni fotókat.

A folyamat áttekintése

  1. Egy vállalati adminisztrátor hoz létre egy API elemet a Skavában: egy űrlapot, valamint a te háttérrendszered címét, módszerét és tokenjét.
  2. Valaki a csevegőben kitölti az űrlapot és elküldi.
  3. A Skava meghívja a backendet és JSON formátumban elküldi a kitöltött értékeket.
  4. A válaszod lesz a kártya a csevegőben.
  5. Opcionálisan később jelenthetsz új állapotokat a visszahívás segítségével. Minden jelentés új kártyát eredményez, a korábbi megmarad.

Követelmények a backendhez

  • HTTPS. Csak https://, ne http, ne legyen hitelesítő adat a címben, legfeljebb 2000 karakter.
  • Közösen elérhető. A hostnak kizárólag nyilvános IP-címekre kell feloldódnia. A localhost, a privát hálózatok, a link-local és a felhőfémadatok elutasítva lesznek, ezt minden hívásnál ellenőrizzük.
  • Rögzített cím. A Skava egyszer oldja fel a hostot, és rögzíti a kapcsolatot az adott IP-címre. A hívás közbeni DNS-változásnak nincs hatása.
  • Nincs átirányítás. A 301-es átirányítás a „helyes” címre is hibának minősül. Azonnal a végső címet add meg.
  • Válaszidő. A időtúllépés elemenként beállítható, de legfeljebb 30 másodperc lehet. Ha hosszabb időre van szükség, azonnal válaszolj, és a callbacken keresztül jelezd később az eredményt.
  • Válasz mérete. A Skava legfeljebb 256 KiB-t olvas be.
  • Content-Type. A törzset csak application/json formátumban elemzi.

A hozzád érkező kérés

A metódus GET, POST, PUT vagy PATCH, az elemtől függően. A POST, PUT és PATCH esetén az értékek JSON törzsként érkeznek, a GET esetén pedig lekérdezési paraméterként.

A hitelesítés egy fejléc, amelynek neve és értéke előtagja az elemben van beállítva, általában Authorization a Bearer előtaggal. A tokent titkosítva tároljuk a mi oldalunkon. A host, content-length, content-type, cookie és accept-encoding fejlécek nem állíthatók be.

A törzs egy lapos objektum. A kulcsokat az elem készítője választja; a beágyazás csak ott jelenik meg, ahol táblázatot vagy termékválasztót adtak hozzá:

{"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": "…"}

Három kulcs mindig tőlünk származik, ezért ne használj őket magad:

  • locale: a felhasználó nyelvkódja. Ebben a nyelvből válaszolj; a szövegeidet mi nem fordítjuk.
  • callback_url és callback_token: az adott interakció visszahívása, lásd lent. Ezek csak akkor jelennek meg, ha a hívás egy csevegésből érkezik.

A kontextusmezők, például a név, a cég, a projekt vagy az alcsevegés, a szerver tölti ki automatikusan, a csatornából, amelyben az elem futott. Egy módosított kliens nem tud ott más projektnevet kijelenteni.

A válasz: a kártya formátum

Válaszolj 2xx kóddal és egy card objektummal. Ez lesz pontosan a chatben megjelenő kártya:

{"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 (kötelező): a 1 egész szám. Szövegként ("1") elutasítják. Ha hiányzik, a válasz nem minősül kártyának, és az elemben beállított válaszleképezés lép életbe.
  • title: a kártya címe.
  • state: csak a szín és az ikon tónusa, az alábbiak egyike: ok, pending, warn, error. Ismeretlen érték esetén a ok értékre esik vissza, és jelet kapsz.
  • status_text: szabad szöveg, amelyet nem értelmezünk. A kártya tetején jelenik meg, és ez az, ami a csevegési listában és a push értesítésben is látható.
  • fields: label és value párok listája. Legfeljebb 20 bejegyzés, label 80 karakter, value 200, title és status_text 120 karakter mindegyik. A túl hosszú értékeket lerövidítjük, nem utasítjuk el: egy rendelésnek nem szabad részletek miatt bukdácsolnia.
  • icon: lásd lent.

Mit csinál a Skava a szövegeiddel, mielőtt azok a csevegésbe kerülnek: a sortöréseket és vezérlőkaraktereket eltávolítjuk (egy jobbról balra írt karakter máskülönben felcserélheti az összeg megjelenését), a backtick karaktereket lecseréljük, és a [SKAVA: kezdettel rendelkező elemeket semlegesítjük. Ez utolsó megakadályozza, hogy egy kártyaértéket más csevegési elemként olvassanak fel, például fizetési kérésként.

A mezőkben, HTML-ben és képekben nem lehet linkeket beállítani. A csevegés egy megbízható környezet, és egy külső backendből érkező kattintható cím bejelentkezési oldal újrakészítésére ösztönözne.

A felhasználó bemeneti adatai a szerverhez tartoznak: az első kártyán jelennek meg, és nem írhatod felül őket. A csevegésben azokat rögzítik, amit ténylegesen beküldöttek.

Ikonok

A icon segítségével a kártya saját jelölést kap a fejlécben. Két lehetőség:

Egy név a beépített készletből: 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.

Vagy saját SVG karakterlábként. Ebből a Skava csak a geometriát veszi át (path, circle, ellipse, rect, line, polyline, polygon a numerikus attribútumaikkal), és saját képet épít. A szkriptek, stílusok, külső hivatkozások, a foreignObject és az eseményattribútumok elhagyásra kerülnek; a doctype vagy entitás megléte elutasítást eredményez; a fájl legfeljebb 8 KiB lehet, és legfeljebb 16 alakzatot tartalmazhat. A szín, a vonalkód és a méretet a Skava állítja be, így az ikon nem álcázhatja magát vezérlőelemként. 24x24-es rácsban dolgozz.

Ha nincs icon, a jelölés alapértelmezett marad.

A visszahívás: későbbi állapotok jelentése

A hívás tartalmazza a callback_url és a callback_token értékeket. Ezekkel jelentheted be a későbbi állapotokat:

POST <callback_url> a Authorization: Bearer <callback_token> és a Content-Type: application/json fejlécekkel, a test mérete legfeljebb 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}

A kártyán kívül három opcionális érték is megadható:

  • seq: a saját számlálód. A kisebb vagy egyenlő értékű jelentés elvetésre kerül, így két jelentés nem előzheti meg egymást. Ha nincs seq, az utolsó érkezett nyert.
  • final: lezárja a kölcsönhatást. A token érvénytelenné válik, és nem jelennek meg további kártyák. Megengedett az első válaszban is, a folytatás nélküli folyamatokhoz.
  • notify: állítsd false értékre, ha a kártyát csendben szeretnéd közzétenni, olvasatlan számláló és értesítés nélkül. Köztes lépésekhez, amelyek nem ébresztik senkit. Ha nincs meg, a kártya teljesen normális üzenet.

Minden jelentés saját kártyává válik a csevegésben, az előző megmarad. Így olvasható, hogy melyik állapotot jelentették. Ebből következik a javaslat: csak a megváltozottat küldd. A kártya, amely negyedszer is ismétli a rendelésszámot, a tételeket és az összeget, csak zaj a olvasó számára.

Két korlát: ugyanaz a jelentés kétszer nem hoz létre második kártyát, és egy kölcsönhatás legfeljebb 50 kártyát tehet közzé. Egy kölcsönhatás 90 napig fogad jelentéseket.

Válaszok, amelyekre reagálnod kell

  • 200 a {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []} testttel. Olvassd el a tippeket: ők jelzik, mi lett rövidítve vagy kihagyva.
  • 401: hibás token vagy interakció azonosító. Ne próbáld újra.
  • 410: az interakció lezárva vagy lejárt. Ne próbáld újra.
  • 422: a kártya nem használható, az okot a hints mező adja meg. Először javítsd ki.
  • 400 hibás JSON, 413 túl nagy, 429 túl sok kérés (ismétlés várakozási idővel), 500 a mi hibánk, később próbáld újra.

1. példa: rendelés státuszhistóriával

1. lépés, a kérés a te háttérszolgáltatásod felé:

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

2. lépés, a te azonnali válaszod:

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

A chat most egy kártyát mutat csomagikonnal, a státusszal és a felhasználó adataival.

3. lépés, később a kiválasztás során:

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

Egy csendes második kártya mezők nélkül: csak az állapot változott.

4. lépés, a szállításnál:

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}

Ez a kártya ébreszthet valakit, ezért nincs notify: false.

5. lépés, a kézbesítésnél:

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

A final értékkel a interakció lezáródik, és a token már nem működik.

2. példa: egy akció utólagos lépések nélkül

Nem minden folyamatnak van előzménye. Egy elem, amely egyetlen mezővel ad át valamit a rendszerednek, csak egy választ igényel:

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

Itt fontos a final: true érték: különben az interakció 90 napig nyitva maradna érvényes tokenel, pedig soha nem jelentesz többet.

Termékválasztó a katalógusból

Amint a cég feltöltötte a cikk-katalógusát, az elem tartalmazhat egy termékválasztó blokkot. A felhasználó ebből állítja össze a kosarat, amit aztán egy lista formájában kapsz meg, a kulcsot pedig az választja meg, aki az elemet felépítette:

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

Mivel a kulcs szabadon megválasztható, ne egy rögzített nevet keress, hanem az első listát, amelynek ez a szerkezete. Küldés előtt a Skava ellenőrzi, hogy minden szám ténylegesen létezik-e az adott cég katalógusában, legfeljebb 50 tétel. A kártyán a tételek lista formájában jelennek meg termékkel, névvel és mennyiséggel.

Tesztelés

  • Az elem szerkesztőjében a Ping egy csupasz HEAD kérést küld token és adat nélkül. Bármivel válaszolhatsz; bármilyen HTTP-válasz érvényesnek számít elérhetőségre.
  • A Próbakérés egy valódi hívást indít mintaadatokkal, még akkor is, ha az elem vázlat állapotban van, és megjeleníti a kérést, a választ, valamint a kártya validáló üzeneteit.
  • Előnézet a mellette lévő fülön: illeszd be a válasz JSON-t, ellenőrizd, és látod a kész kártyát a tippekkel együtt. A szerveren ugyanazzal a kóddal ellenőrizzük, mint éles környezetben.
  • Példa szerver: egy teljes példa szolgáltató fut az api.skava.io címen, és használja a fent leírt összes funkciót. A forráskódja a repóban található az example_order_server/ mappában, kb. 600 sor tiszta standard könyvtárral, másolásra szánt.

Mit érdemes még tudni

  • A kártya egy tökéletesen normális chatüzenet. Megjelenik a keresésben, idézhető, és megmarad az előzményekben.
  • A rendszerküldő adja le, nem a céged egy fiókja. Mégis az oldalán jelenik meg, aki futtatta az elemet, és a címben szerepel, hogy melyik rendszer írja.
  • Aki futtathatja, azt az elemen állítják be: csak a cég tagjai, vagy külsősök is, akik egy chatet osztanak vele. Ha a céged kilép a chatből, a jogosultság magától megszűnik.
  • A lejárt tokenű API elem inaktív: a jelenlegi alkalmazások rejtik el a menüből, és a mégis elküldött hívást a szerver elutasítja. Egy adminisztrátor új tokent tárolhat számára, ami a kiadott felületen is működik.

Kapcsolódó

Létrehozás és kiadás: Egyedi elemek: API felületek. Kitöltendő dokumentumok a felületek helyett: Egyedi elemek: Dokumentumok.