Doplnky - Vývoj doplnku (technická dokumentácia)

Rozcestník:

• Vytváranie a správa doplnku
  • Vývoj doplnku
    • Verifikácia doplnku
    • Aktivácia doplnku
    • Otvorenie doplnku
      • Iframe doplnku
    • Deaktivácia doplnku
    • Testovanie doplnku
    • Verzovanie doplnku (zmena fungovania)
  • API dokumentácie (ako prepojiť produkty, kategórie, objednávky, atď)
    • Automatická kontrola a Obmedzenie API doplnku
  • Pravidlá a Best Practices
    • Všeobecné pravidlá
    • Aktivácia doplnku
    • Otvorenie doplnku
    • Fungovanie doplnku
    • Základné očakávané funkcie doplnku
  • Webhooky
  • Discord Developer forum (Chcete vedieť čo sa chystá, alebo len potrebujete poradiť?)

Vývoj doplnku

Vývojová časť doplnku (záložka Vývoj doplnku) slúži na napojenie doplnku do Upgates administrácie a je rozdelená na dve sekcie.

TIP! Než začnete doplnok vytvárať, aj keď ste prešli úvodnou online konzultáciou, neváhajte hneď zo štartu založiť ticket z vášho vývojového projektu (prípadne napíšte na Discord) a preberme krok za krokom ako by sa mal doplnok správať od aktivácie, cez bežnú prevádzku až po špeciálne prípady ako napríklad čo robiť s doplnkom, keď klient prestane vašu. Radšej vždy pomôžeme v priebehu vývoja samotného doplnku, než aby sme narazili na prekážky v schválení doplnku až pri samotnom testovaní.

ENDPOINTY

Sekcia Endpointy sa skladá z dvoch častí API nastavenia a API prístupy.

Pozor! Pre správne fungovanie doplnku (aktiváciu) je nutné vyplniť obe tieto sekcie.

API nastavenia

V sekcii API nastavenia nájdete endpointy, ktoré musíte na svojej strane vytvoriť. Z našej strany na ne budú chodiť požiadavky týkajúce sa funkcie doplnku.

Endpointy musia byť verejne dostupné a vyžadujeme SSL certifikát na všetkých API endpointoch.

(screen z Marketplace / Moje doplnky - Váš doplnok - Vývoj doplnku)

• Inštalačný endpoint: Slúži pri aktivácii doplnku zo strany klienta.
• Otvárací endpoint: Slúži na otvorenie Iframe časti doplnku. Z našej strany posielame informáciu Klient X, s tokenom Y chce otvoriť váš doplnok. Z vašej strany vraciate v tele požiadavke adresu daného iframu.
• Odinštalačný endpoint: Slúži pri pri deaktivácii doplnku. Z našej strany posielame informáciu, že klient doplnok deaktivoval a mažú sa API prístupy. Nie je potrebná vaša odpoveď.
• Verzovací endpoint: Slúži k prípadom kedy zákazník bude prechádzať na novú verziu doplnku, na túto adresu sa následne zasiela informácia na akú verziu prechádza, aby ste mu mohli vrátiť správne informácie napríklad do iframu/založiť konverzný kód, atď.
• Signature_token: Jedinečný identifikátor k vášmu doplnku, slúžiaci na zostavenie podpisu (viď Aktivácia, Otvorenie, Zmena verzie a Deaktivácia)

API prístupy

Tieto API prístupy je nutné navoliť podľa toho, ako váš doplnok pracuje.
Napríklad: Pokiaľ potrebujete sťahovať objednávky, založíte Typ prístupu Objednávky, časť GET Objednávky, a nastavíte frekvenciu v akej budete GET prevolávať.

Popis účelu využitia API prístupu: Slúži pre nás ako informácia o tom, prečo API prístup potrebujete a akú u vás plní funkciu.
Frekvencia volaní: slúži pri automatickej kontrole vášho doplnku. Automatická kontrola vyhodnocuje či sa váš doplnok drží v nastavených medziach. Táto kontrola je pre nás dôležitá, aby pravidelne nebolo preťažované API a nefunguje inak, než spôsobom, ktorý sme si povedali v konzultácii, alebo pri testovaní z našej strany.

Pozor! Dbajte prosím na správny a detailný popis frekvencie prevolávania a popisu účelu prečo daný API prístup zakladáte.

Pravidlá a Best practices

Základným cieľom overeného doplnku je priniesť klientom čo najväčšiu automatizáciu v prepojení bez zbytočných klikaní a vyplňovaní formulárov.

Využívajte vždy aktuálne logá Upgates.

Všeobecné

• Doplnok funguje vďaka komunikácii cez API. Základné BestPractices v používaní API nájdete tu.
• V prípade práce s API viacerých e-shopov na jednom serveri je potrebné vyťaženie rozdeliť časovo počas celého dňa, a nesťahovať dáta napr. iba počas noci alebo o 00:00 a pod.
  Napr. si rozdeliť pool e-shopov a pridávať offsety po hodinách alebo iných väčších časových úsekoch:
  • 2 e-shopy o 00:00
  • 2 e-shopy o 01:00
    atď.
• Brať do úvahy, že Upgates umožňuje multijazyčnosť a multidoménovosť.
  • Čo to pre vás znamená?
    Je potrebné sa pripraviť na to, že produkty, kategórie, články, a ďalšie sekcie sú vo viacerých jazykoch pod viacerými doménami, ale iba pod jednou administráciou.
    Teda napríklad produkt „Tričko“ môže byť v jazyku CZ, SK, EN, môže mať pre každú mutáciu vlastnú doménu, ale stále bude v jednej administrácii pod jedným jedinečným ID.
    Ďalej môže byť produkt "Bunda", ktorý bude v jazyku iba SK, ale stále bude spadať pod tú istú administráciu ako produkt "Tričko".
  • Ak riešite multijazyčnosť pri produkte, kategóriách atď. Sťahujte ich ako celok (bez obmedzenia URL na jazyky).
    Rozdelenie na samotné jazyky vyriešte až na svojej strane. Sťahovanie konkrétnych jazykov by ste mali využiť napríklad v momente, keď riešite vec týkajúcu sa konkrétnej jazykovej mutácie. Napríklad reakciu na webhook languages.create – kedy vzniká nová jazyková mutácia.
• Využívajte webhooky - Porušenie môže spôsobiť neschválenie doplnku, poprípade neskoršiu blokáciu pokiaľ je zistené automatickou kontrolou.
• Testovanie doplnku:
  • Hlavným atribútom pri testovaní doplnkov z vašej strany, by mala byť užívateľská prívetivosť. Než nám doplnok odovzdáte na testovanie, prosím overte si, že dokážete váš doplnok obsluhovať ako bežný zákazník (správne sa vytvorí užívateľský účet, funguje odhlásenie a opätovné prihlásenie do vášho prostredia, atď.). Uľahčí sa tým celkový proces schvaľovania doplnku.
  • Hlavným cieľom pri kontrole z našej strany vášho doplnku, bude zaistiť čo najlepšie používanie API.
  • Nepoužívajte tlačidlo "Synchronizovať". Pokiaľ ho pre fungovanie naozaj potrebujete, nastavte u neho ochranu opakovaného klikania, a tiež aby nebolo možné tlačidlo stlačiť znova, pokiaľ beží ešte pôvodný proces synchronizácie.
  • Plánované úlohy vykonávajte s webhooky. Nie je nutné každý deň sťahovať všetky objednávky, zvlášť v prípade, keď nevznikla žiadna nová objednávka / neprebehla žiadna zmena.

Aktivácia doplnku

• Pri návrhu doplnku by ste mali počítať s tým, že z našej strany, aj keď nie priamo cielene, môže prísť viac požiadaviek na aktiváciu, už aktivovaného doplnku alebo aj požiadavku na deaktiváciu, aktuálne neaktívneho doplnku.
• Aktiváciu (prípadne následnú registráciu) je možné brať ako už overenú (autorizovanú). Vykonáva ju totiž vždy užívateľ v Upgates.

Založenie účtu

• Na založenie alebo spárovanie účtu môžete využiť /owner.
• Založenie účtu plne automatizujte. Nevyžadujte po klientovi vyplnenie špeciálneho formulára na vašich stránkach. Klient je overený z našej strany, teda registráciu priamo u vás je možné realizovať, bez zbytočných prieťahov.
  • Pokiaľ z /owner a ďalších endpointov nezískate všetky potrebné údaje pre registráciu vyriešte pomocou iframe okna.
  • Akonáhle získate informácie z owner, založte zákazníkovi účet tak, aby sa dostal rovno do vášho prostredia bez zbytočných prieťahov. Nevyžadujte po zákazníkovi dodatočné kopírovanie overovacích kódov z e-mailov, kopírovanie prepojovacích tokenov, atď.
• Ak vaše prostredie vyžaduje uviesť, že účet je prepojený s danou platformou Upgates, musí sa tak stať počas zakladania účtu. Nevyžadujte po zákazníkovi dodatočnú aktiváciu prepojenia na svojej strane.
• Užívateľ nesmie mať prístup k API prístupovým údajom, ktoré sa vám cez doplnok zasielajú. Tieto komunikačné údaje slúžia len pre vás a klient by ich nemal mať možnosť nijako zistiť a ďalej používať.

Otvorenie doplnku

• Riadia sa pravidlami používania iframe doplnku.
• Pokiaľ všetko v rámci spárovania existujúceho zákazníka a registrácia nevého prebieha automaticky, nie je nutné iframe používať.
• (Odporúčame) Cez iframe môžete poskytnúť nastavenie vašej aplikácie klientovi tak, aby vôbec nemusel opustiť administráciu Upgates a bolo tak pre neho všetko komfortnejšie a rýchlejšie.

Fungovanie doplnku

• Tlačidlo Synchronizovať / Aktualizovať
  Pokiaľ potrebujete mať vo svojom doplnku tlačidlo na sťahovanie aktuálnych dát (napríklad objednávok), myslite najskôr na povinnosť webhooky. Pokiaľ dané tlačidlo musí byť skutočne uvedené, odporúčame ho nastaviť tak, aby nebolo možné používať opakovane behom pár sekúnd. Použitie musí byť podmienené minimálne vždy tak, aby sa dalo aktivovať až po dokončení predchádzajúceho sťahovania + napríklad nejaký interval.
  Ak pred X sekundami prebehlo stiahnutie zmien, nemalo by tlačidlo pre aktualizáciu prevolávať znova API.
• Webhooky (dokumentácia tu)
  • Webhooky nesmie ísť vo vašom prostredí užívateľsky obísť!
  • Pokiaľ zákazníkovi ponúkate možnosť nastavenia synchronizácie opakovane napríklad v rádoch jednotiek minút. Musia sa tieto časové spúšťače vykonávať na vašej strane a kontrolovať, či počas tohto intervalu nedorazila notifikácia z webhooku. Nie je možné prevolávať jednotlivé sekcie napríklad čo minútu a obchádzať takto webhooky.

Typy jednotlivých doplnkov

V tomto odseku sa pokúsime popísať základné očakávané využitie API a fungovanie jednotlivých typov doplnkov. Pokiaľ tu nenájdete popis svojho doplnku, neváhajte nás informovať a spoločne môžeme ideálny stav fungovania doplnku prebrať na online schôdzke.