Books Chcete vytvářet aplikace pro platformu Mergado, ale nevíte jak na to? Připravili jsme pro vás sérii článků, které by vám s tímto mohly alespoň trochu pomoct. Původně mělo jít o krátký tutorial, který se mi však nějakým záhadným způsobem rozrostl pod rukama. Proto jsme se rozhodli, že bude lepší, když vám takovou nálož nových informací naservírujeme postupně.

Kde se naše platforma vzala? Proč byste měli aplikace vůbec psát? Kde na ně vzít nápady? Co vlastně založení takové aplikace obnáší? To vše se dozvíte v dnešním prvním dílu – Seznámení s platformou.

Úvodní slovo#

Protože se tedy nakonec ukázalo, že nepůjde o jeden tutorial, ale spíše o několik článků, tak si programování necháme až na přístě. Nicméně určitě se už nyní bude hodit informace o tom, že aplikace pro Mergado jsou poháněné populárním jazykem PHP. V této sérii tak budeme předpokládat, že nějaké zkušenosti s tímto jazykem vývojář již má. Rovněž předpokládáme, že vývojář:

  • ovládá alespoň základy práce s linuxovým terminálem,
  • má představu o existenci něčeho, čemu se říká SSH,
  • ví, co je to HTML a CSS a
  • už má vybraný nějaký svůj oblíbený editor, ve kterém svou první aplikaci bude psát.

Pokud vůbec netušíte, co Mergado je a proč byste pro něj vůbec měli psát aplikace, můžete se s celou ideou Mergada seznámit na jeho hlavním webu Mergado.cz. Stejně tak pokud se vám bude zdát nějaká technická záležitost nedostatečně vysvětlená či prostě budete chtít podrobnější přehled o tom, jak platforma funguje, můžete se také kdykoliv ponořit do oficiální vývojářské dokumentace (v angličtině).

Trocha historie#

Evolution

Myšlenka otevřít ekosystém Mergada světu (resp. vývojářům třetích stran) se neobjevila ze dne na den. Šlo o výsledek několikaletého vývoje a rozjímání nad tím, jak našim uživatelům co nejjednodušeji a nejefektivněji zpřístupnit co nejlepší funkce, které by jim mohly pomoci navyšovat tržby u e-shopů, jež spravují.

Celé to začalo v roce 2014, kdy jsme jádro Mergada rozšířili o sadu prémiových funkcí, které jsme nazvali Mergado VIP. Prakticky šlo pouze o "glorifikované" audity výstupního XML, v rámci kterých se nevyhodnocovala pouhá validnost výstupního XML, ale braly se v potaz i externí signály, jako třeba statistické reporty z Heureky, nákladové feedy a podobně. Z těchto "rozšířených auditů" postupem času vykrystalizoval nápad vytvořit univerzální a snadno rozšiřitelné řešení. Dopadlo to tak, že jsme funkce, které původně tvořily gró Mergado VIP, vylepšili a přesunuli do dvou samostatných celků, tzv. aplikací. Tyto dvě první aplikace, Heureka Watchdog a Pricing Monitor vlastně byly důvod, proč jsme spustili Mergado Store, o kterém jste možná již slyšeli (dobový blogpost zde).

Jak plynul čas a rostl počet uživatelů našich aplikací, snažili jsme se tu a tam vytvořit i nějakou novou appku, která by našim uživatelům opět o něco zjednodušila život. Mezitím bylo samozřejmě nezbytné pracovat i na samotném Mergadu; provádět každodenní údržbu, vyvíjet jeho jádro a nadále rozšiřovat jeho funkce. Jak se ukázalo, udržovat dvě úrovně vývoje Mergada je náročná práce. Po nějaké době jsme se tak začali čím dál častěji sami sebe ptát: "Jak vylepšit možnosti rozšiřování funkcionality Mergada bez toho, abychom se připravovali o čas, který bychom rádi investovali do vývoje jádra, do jeho stability, rychlosti a nových funkcí? Co kdybychom tvorbu aplikací zpřístupnili i ostatním vývojářům – mimo náš tým, mimo naši společnost?"

Zbytek příběhu už možná znáte. Po dlouhém plánování, navrhování systémů, po měsících programování a po obrovském množství vypitého kafe jsme v září 2016 spustili veřejnou verzi platformy Mergado, ve které si každý, kdo chce, může naprogramovat vlastní aplikaci, která poběží v rámci naší služby Mergado.

It is done

Co může aplikace dělat?#

Pokud už o Mergadu máte nějaký přehled či v něm dokonce pravidelně pracujete, tak vás možná někdy napadlo, jak byste chtěli funkcionalitu jádra Mergada – pro sebe i pro ostatní uživatele – rozšířit. Je také možné, že s Mergadem sami nepracujete a k vývoji aplikací vás táhne spíše finanční odměna (samozřejmě kromě extatického zážitku z vývoje). V obou případech platí, že cokoliv, co uživatelům usnadní práci, je vítáno. Může se jednat například o kontrolu obsahu feedu (odpovídají EANy u produktů?) či o nějaké automatizované zpracování signálů z vyhledávačů zboží a z jiných zdrojů. Neměl by např. být problém vytvořit aplikaci, která pomocí externí služby určitým produktům upraví cenu za proklik na základě předpovědi počasí. Fantazii se meze nekladou. Pokud by vás Múza přesto nepolíbila, můžete se nechat inspirovat u již existujících aplikací v již zmiňovaném Mergado Store, nebo můžete zkusit napsat k nám na podporu, kde nějaké nápady zrají v šuplíku.

Co bude umět naše aplikace?#

Vytvořím s vámi jednoduchou aplikaci, která uživateli, jenž si ji zapne u svého exportu, vrátí uživatelovo jméno a seznam všech produktů, jejichž cena bez DPH je méně, než 100.

Jak se stát vývojářem?#

Aby se člověk mohl stát vývojářem, musí být uživatelem Mergada – to tedy znamená, že vy, jakožto vývojář, máte v Mergadu účet. Pokud jej nemáte, musíte si jej založit zde. Nebojte se políčka fakturační období, které se vztahuje pouze na majitele opravdových e-shopů. Uvnitř Mergada je pak třeba přejít do sekce, která je určená vývojářům aplikací. Zde bezostyšně přiznáváme naši lenost a tuto vývojářskou sekci jsme pojmenovali jednoduše (avšak výstižně) "Developers".

Nakonec, pokud jste v této sekci poprvé a nejste v databázi Mergada vedeni jako vývojáři aplikací, je na vás, abyste se tak sami označili.

How to become an app developer

Testovací data#

Pokud jste v Mergadu účet zatím ještě neměli, je pravděpodobné, že stejně tak nebudete mít žádná testovací data, na kterých si vaši aplikaci budete testovat. V současné době v Mergadu horlivě vymýšlíme, jak nějaká testovací data vývojářům snadno, rozumně a bezpečně poskytnout. Do té doby si však vývojáři musí sehnat data vlastní, případně se mohou obrátit na podporu Mergada, kde se vám je pokusíme zajistit.

V této sérii budeme předpokládat, že nějaká testovací data už máte. Já jsem si pro účely tutorialu testovací data – XML feed podle specifikace Mergado XML – vytvořil sám. Jedná se o XML feed definující sortiment fejkového e-shopu Fakedevshop-B95509D2Feefdda5Cb6Da57C2Fec4B33.com (to abych se při importu takového feedu zcela jistě netrefil do názvu e-shopu, který by v Mergadu mohl již existovat), který se skládá ze tři druhů různě barevných pastelek.

<CHANNEL xmlns="http://www.mergado.com/ns/1.2">
    <LINK>http://www.fakedevshop-b95509d2feefdda5cb6da57c2fec4b33.com/</LINK>
    <GENERATOR>manual</GENERATOR>
    <ITEM>
        <ITEM_ID>0001</ITEM_ID>
        <EAN>0000000000001</EAN>
        <NAME_EXACT>Červená pastelka</NAME_EXACT>
        <NAME_COMMERCIAL>Červená pastelka, extra drsná</NAME_COMMERCIAL>
        <CATEGORY>Kreativa | Pastelky</CATEGORY>
        <DESCRIPTION>Toto je moc krásná červená pastelka</DESCRIPTION>
        <IMAGE>http://www.fakedevshop-b95509d2feefdda5cb6da57c2fec4b33.com/img/moje-prvni-aplikace/cervena-pastelka.jpg</IMAGE>
        <IMAGE_ALTERNATIVE>http://www.fakedevshop-b95509d2feefdda5cb6da57c2fec4b33.com/img/moje-prvni-aplikace/cervena-pastelka-2.jpg</IMAGE_ALTERNATIVE>
        <BRAND>Straka a syn</BRAND>
        <URL>http://www.fakedevshop-b95509d2feefdda5cb6da57c2fec4b33.com/cervena-pastelka</URL>
        <CURRENCY>CZK</CURRENCY>
        <PRICE>100</PRICE>
        <PRICE_VAT>121</PRICE_VAT>
        <CONDITION>new</CONDITION>
        <CPC>10</CPC>
        <PARAM>
            <NAME>Barva</NAME>
            <VALUE>Červená</VALUE>
        </PARAM>
    </ITEM>
    <ITEM>
        <ITEM_ID>0002</ITEM_ID>
        <EAN>0000000000002</EAN>
        <NAME_EXACT>Modrá pastelka</NAME_EXACT>
        <NAME_COMMERCIAL>Modrá pastelka, extra měkká</NAME_COMMERCIAL>
        <CATEGORY>Kreativa | Pastelky</CATEGORY>
        <DESCRIPTION>Toto je moc krásná modrá pastelka</DESCRIPTION>
        <IMAGE>http://www.fakedevshop-b95509d2feefdda5cb6da57c2fec4b33.com/img/moje-prvni-aplikace/modra-pastelka.jpg</IMAGE>
        <IMAGE_ALTERNATIVE>http://www.fakedevshop-b95509d2feefdda5cb6da57c2fec4b33.com/img/moje-prvni-aplikace/modra-pastelka-2.jpg</IMAGE_ALTERNATIVE>
        <BRAND>Straka a syn</BRAND>
        <URL>http://www.fakedevshop-b95509d2feefdda5cb6da57c2fec4b33.com/modra-pastelka</URL>
        <CURRENCY>CZK</CURRENCY>
        <PRICE>89</PRICE>
        <PRICE_VAT>101</PRICE_VAT>
        <CONDITION>new</CONDITION>
        <CPC>8</CPC>
        <PARAM>
            <NAME>Barva</NAME>
            <VALUE>Modrá</VALUE>
        </PARAM>
    </ITEM>
    <ITEM>
        <ITEM_ID>0003</ITEM_ID>
        <EAN>0000000000003</EAN>
        <NAME_EXACT>Zelená pastelka</NAME_EXACT>
        <NAME_COMMERCIAL>Zelená pastelka, extra průměrná</NAME_COMMERCIAL>
        <CATEGORY>Kreativa | Pastelky</CATEGORY>
        <DESCRIPTION>Toto je docela pěkná zelená pastelka</DESCRIPTION>
        <IMAGE>http://www.fakedevshop-b95509d2feefdda5cb6da57c2fec4b33.com/img/moje-prvni-aplikace/zelena-pastelka.jpg</IMAGE>
        <IMAGE_ALTERNATIVE>http://www.fakedevshop-b95509d2feefdda5cb6da57c2fec4b33.com/img/moje-prvni-aplikace/zelena-pastelka-2.jpg</IMAGE_ALTERNATIVE>
        <BRAND>Straka a syn</BRAND>
        <URL>http://www.fakedevshop-b95509d2feefdda5cb6da57c2fec4b33.com/zelena-pastelka</URL>
        <CURRENCY>CZK</CURRENCY>
        <PRICE>120</PRICE>
        <PRICE_VAT>142</PRICE_VAT>
        <CONDITION>used</CONDITION>
        <CPC>14</CPC>
        <PARAM>
            <NAME>Barva</NAME>
            <VALUE>Zelená</VALUE>
        </PARAM>
    </ITEM>
</CHANNEL>

Takto ručně vytvořené XML jsem uložil někam na internet a následně jsem jej importoval do Mergada, kde se mi tak vytvořil nový e-shop a u něj první export. Pokud netušíte, jak takový XML feed do Mergada nahrát, můžete se více dočíst např. zde.

Vytvoření aplikace#

Doteď jsme nápad měli v hlavě; možná jsme si i nakreslili nějaké návrhy, jak naše aplikace bude fungovat a vypadat. Platforma však o naší aplikaci zatím nic neví a proto je nejvyšší čas ji o ni říct – je čas aplikaci v Mergadu opravdu vytvořit.

Hlavní stránka sekce Developers zobrazuje seznam všech aplikací, ke kterým má vývojář přístup. Já ho mám momentálně prázdný, protože jsem zatím žádnou aplikaci nevytvořil a ani nemám přístup k žádné aplikaci někoho jiného. K formuláři, který nám umožní vytvoření nové aplikace, se dostaneme kliknutím na boxík se symbolem +. Na stránce, která se nám následně objeví, definujeme základní vlastnosti naší nové aplikace.

Form

Vývojový tým#

Každý vývojář pro platformu Mergado patří do nějakého vývojového týmu. Když se z běžného uživatele stane vývojář, tak je v ten okamžik zařazen do svého "osobního" týmu, který se mu automaticky vytvoří. Protože v tuto chvíli jsem členem pouze jediného týmu (mého vlastního), momentálně se zde nenabízí jiná možnost.

Název aplikace#

Pod tímto názvem se bude aplikace prezentovat v celém Mergado ekosystému. Takto bude vidět v Mergado Store, takto se jejím uživatelům bude ukazovat ve fakturaci a takto se o ni bude psát, až bude slavná. Název vybíráme pečlivě, nedá se již změnit; v rámci platformy musí být název jedinečný a aby měli uživatelé Mergada mezi všemožnými aplikacemi snazší orientaci, měl by být alespoň trochu výstižný. Název po založení aplikace nelze změnit.

Typ aplikace#

Typ aplikace se odvozuje od toho, jakým způsobem se s ní má pracovat: jaké je její zaměření a na kterých místech má být k dispozici, kde se má zobrazovat widget a podobně.

Práce běžných uživatelů se totiž v rámci aplikace Mergado může odehrávat na třech odlišných úrovních (u nás v Mergadu těmto úrovním říkáme kontexty), podle toho, kde se přihlášený uživatel právě nachází. Když se uživatel nenachází uvnitř administrace žádného e-shopu, jedná se o kontext uživatele. Pokud se nachází v administraci konkrétního e-shopu, ale nikoliv uvnitř konkrétního exportu v tomto e-shopu, jedná se o kontext e-shopu. Nakonec, když se uživatel nachází v administraci konkrétního exportu, jde o kontext exportu. Tyto kontexty si spíše než jako oddělené nádoby představte tak, že se na sebe "nabalují":

Context hierarchy

Podle toho, v jakém místě této hierarchie má aplikace své nejpřirozenější místo, si vývojář zvolí její typ. V různých kontextech má aplikace zaručená různá data. Pokud se například aplikace vztahuje na export (její typ je project), jakožto vývojáři aplikace se můžeme spolehnout na to, že aplikace vždy bude mít nějaký konkrétní export, se kterým bude pracovat (nikde jinde - např. v kontextu e-shopu - appku Mergado prostě nezobrazí.) Oproti tomu aplikace typu user má jisté jen to, že "dostane" konkrétního uživatele. Protože je ale kontext uživatele nadřazený všem ostatním kontextům (shop a project), aplikace se v Mergadu může zobrazit i u konkrétního e-shopu či exportu. Je pak na dané aplikaci, jak se s takovou situací vyrovná a zda tyto "extra kontexty" bude zohledňovat či nikoliv.

Data, která má aplikace na základě svého typu zaručeně k dispozici, nazýváme entitami. Zapnuté aplikace se pak na tyto konkrétní entity vážou. Můžeme tak říct, že např. "aplikace typu user je zapnutá u konkrétní entity user s ID 12345)". V návaznosti na tři druhy kontextů tak tedy existují tři druhy entit:

  • Uživatel (user) – Aplikace může být zapnutá pro konkrétního uživatele; bude k dispozici všude, kde je uživatel.
  • E-shop (shop) – Aplikace může být zapnutá u konkrétního e-shopu; k dispozici bude v rámci tohoto e-shopu (tedy i uvnitř všech jeho exportů).
  • Export (project) – Aplikace může být zapnutá u konkrétního exportu; bude k dispozici pouze v rámci tohoto konkrétního export.

tl;dr#

Vybraný typ aplikace definuje její pole působnosti; např. na jakých místech v Mergadu se aplikace bude zobrazovat a s jakými daty bude moci pracovat. (více v dokumentaci) Typ aplikace po jejím založení nelze změnit.

Délka zkušebního období#

Good samaritan

Aplikace pro Mergado mohou být zdarma anebo placené - pokud chceme, aby uživatelé za používání naší appky měsíčně platili. V případě placené aplikace si ještě můžeme rozhodnout délku zkušebního období, po jehož dobu bude užívání nově zapnuté aplikace zcela zdarma.

Protože máme dobrou náladu, chceme býti dobří samaritáni, nebo protože si chceme ušetřit nervy s neplatiči, rozhodli jsme se, že naši první aplikaci budeme uživatelům poskytovat zdarma.

Barva#

Pro odlišení se od ostatních můžeme naší aplikaci přiřadit nějakou zajímavou barvu. Může to být naše oblíbená barva nebo třeba primární barva podle loga naší aplikace.

Podporované formáty exportů#

Pokud je aplikace typu export, je také možné (nutné) zadefinovat, pro které výstupní formáty bude k dispozici. Protože moje aplikace bude pro exporty a protože chci podporovat pouze exporty, jejichž výstupní formát je Mergado XML, zaškrtnu jen ten jediný.

Přístupová práva#

Na tomto místě si můžeme vybrat z možných přístupových práv (OAuth2 oprávnění), které naše aplikace potřebuje. V mé aplikaci budu chtít číst informace o aktuálně přihlášeném uživateli a informace o projektu (exportu), u kterého je appka zapnutá. Zaškrtnu tedy user.read a project.read. Seznam práv, které aplikace ke svému fungování vyžaduje, se vašim potenciálním uživatelům zobrazí v Mergado Store. Tím, že bychom pro naši aplikaci požadovali práva, která na první pohled určitě nepotřebuje, můžeme riskovat, že obezřetní či opatrní uživatelé si naši aplikaci nezapnou. Kompletní přehled existujících práv s popisem toho, co je s nimi možné dělat, naleznete v dokumentaci.

Podporované země#

Zde si určíme cílové trhy, na kterých bude naše aplikace k dispozici. Pokud zde zaškrtneme zemi, znamená to: "uživatelé Mergada, kteří mají odpovídající fakturační adresu, si mohou naši aplikaci zapnout". V tomto případě nás zajímá pouze Česká republika a Slovensko, takže zaškrtnu tyto země. Aplikaci si tak budou moci zapnout uživatelé z Česka a ze Slovenska a ti z ostatních zemí ji v Mergado Store sice uvidí, ale bez možnosti ji aktivovat či spravovat.

Odeslání formuláře#

Když máme vše potřebné nastavené, vybrané a zkontrolované, můžeme pokračovat stiskem tlačítka Vytvořit aplikaci. V ten okamžik se do Mergada zašle informace o tom, že chceme vytvořit novou aplikaci, spolu se všemi jejími nastavenými parametry.

Mohutné stroje, jenž lidé zovou "servery", do této chvíle dřímající v potemnělém šeru, náhle procitnou z tichého odpočinku a za děsivého hučení začnou připravovat prostor pro naši novou aplikaci.

Co bude příště?#

V dalším dílu série již budeme mít aplikaci vytvořenou a tak se budeme moci podívat na její administraci, kterou budeme mít jako její vývojáři v rámci Developers k dispozici. Vyzkoušíme si připojení na cloud, kde naše aplikace bude žít, a když vše dobře půjde, tak třeba už napíšeme i nějaký ten kód.