🚧 Novinky v platformě pro vývojáře

vývojáři-aplikací
mergado-aplikace
vývojáři

#21

:cloud: Mergado Apps 0.3.17

Release date

13. červen 2018

Změny

  • Nové atributy pro API endpoint /shops/{id}/stats/ (dokumentace)
    • Atribut heureka_total_sales vrací data o celkových tržbách pro daný e-shop za zvolené období.
    • Atribut heureka_total_orders vrací data celkovém počtu objednávek pro daný e-shop za zvolené období.
    • Issue platformy: Add Heureka sales and orders to /shops/[id]/stats/ #83
  • Endpointy, které vrací statistiky vztahující se na celý eshop, nyní mají scope shop.stats.read
    • /shops/{id}/stats/
      • Změněn scope z project.stats.read na shop.stats.read
    • /products/{id}/stats/
      • Vrací pouze obecné statistiky a statistiky vztahující se k danému projektu
      • project_id se získá podle product_id
      • Obecnými statistikami jsou id, item_id, date, shop, cost, is_starter a is_topseller
      • Pokud by měl být field product_id==null, nevrátí se vůbec.
    • /projects/{id}/stats/products/
      • Vrací pouze obecné statistiky a statistiky vztahující se k danému projektu
      • Pokud se pro daný formát nestahují statistiky, je vrácen prázdný seznam
      • Pokud by měl být field product_id==null, nevrátí se vůbec.
    • /shops/{id}/stats/products/
      • Nový endpoint
      • Vrací statistiky produktů ze všech zdrojů api
    • /projects/{id}/stats/categories/
      • Odstraněn, nahrazen novým endpointem na URL /shops/{id}/stats/categories/
      • Vrací to samé, jako endpoint, který nahrazuje
      • Vyžaduje scope shop.stats.read
    • /projects/{id}/stats/audits/
      • Odstraněn, nahrazen novým endpointem na URL /shops/{id}/stats/audits/
      • Vrací to samé, jako endpoint, který nahrazuje
      • Vyžaduje scope shop.stats.read
    • /stats/audits/{m3shop_id}-{date_id}/
      • Změněn scope z project.stats.read na shop.stats.read
    • /stats/audits/{m3shop_id}-{date_id}/issues/
      • Změněn scope z project.stats.read na shop.stats.read

#22

:ribbon: Mergado Apps 0.3.18

Release date

27. červen 2018

Změny

  • Aplikace nyní mohou používat jiné úložiště, než je Mergado Appcloud.

    • Většina dalších změn, které jsou uvedeny níže, vychází z této změny, která v některých oblastech zásadně mění paradigma, v jakém appky existují a fungují.
    • U appky v Developers je nová stránka Úložiště, kterou může vývojář použít ke správě úložiště zvlášť vývojové a zvlášť produkční verze appky.
      • Defaultní úložiště je vždy Appcloud. Potom lze každé verzi appky nastavovat jiné URL, které Mergado používá:
        1. Při odesílání hook requestů.
        2. Při posílání payloadů na endpointy pravidel appky.
        3. Pro zobrazení IFRAMEů (widget i plná verze) při zobrazování appky v UI.
      • Pokud alespoň jedna verze appky nepoužívá Appcloud úložiště, pak při vytváření nového vydání na stránce Releases není možné spouštět tradiční release proces na Appcloudu.
      • Hook URL musí začínat stejnou URL, jako je Základní URL appky.
      • Lze nastavovat způsob routingu aplikace. Oproti stávajícímu pretty routingu ve stylu:
        .../eshop/1/project/2
        
        … lze nově nastavit i jednodušší routing přes GET parametry:
        .../?eshop=1&project=2
        
  • Přepracovaný a zjednodušený životní cyklus aplikace.

    • Možnost “soběstačných” releasů aplikace.
      • Umožňuje použití pokročilejších CI a CD nástrojů.
      • Aplikace nově nepodléhá tradičnímu cyklickému vývoj-žádost o release-potvrzení podporou-release-vývoj....
      • Nové verze si vývojář řeší a vydává sám, bez explicitního potvrzování podporou Mergada.
        • Pokud vývojová i produkční verze aplikace užívá Appcloud úložiště, lze tradiční “appcloudovský” release spouštět i nadále - při vytvoření nového vydání na stránce Releases v Developers je k dispozici checkbox, který toto zajistí. (Více o této přepracované stránce níže.)
        • Pokud alespoň jedna verze na Appcloudu nesídlí, celý releasovací proces si musí vývojáři řešit sami. To však zároveň vývojářům umožňuje integraci pokročilých build či CI systémů do jejich vývojové workflow. A toto vše je možné, protože…
    • Nově má vývojář aplikace SSH přístup k oběma verzím appky (dříve byl přístup pouze k vývojové verzi).
      • Autoři aplikace tak mají větší kontrolu nad tím, co se s aplikací děje - např. je potřeba mít přístup k logům, je potřeba urychleně vydat fix nějaké chyby, nebo si vývojáři chtějí nakonfigurovat složitější build procesy přes nějaké externí CI nástroje.
      • Tradiční schvalovací proces toto zásadně brzdil či zcela znemožňoval.
    • Informace v Mergado Store se nyní “přelévají” tlačítkem Aktualizovat Store, bez předchozí kontroly podpory (je však o tomto aktu notifikována).
      • Poznámka: Informace se přelejí automaticky i při vytvoření nového release.
    • Přes to všechno má naše podpora v případě potřeby stále možnost zasáhnout a “zlobivou” aplikaci např. skrýt z Mergado Store, či ji u některého subjektu přímo vypnout.
  • Přepracovaná stránka Releases v Developers.

    • Namísto historie stavů mezi vývoj-žádost o release-potvrzení podporou-release-vývoj... jsou nyní na stránce s výdánímí appky vypsané běžné záznamy s novými verzemi aplikace, které vývojář může vytvářet, editovat i mazat.
    • Zatím se tato historie ukazuje jen v Developers a momentálně je především pro interní účely, aby podpora Mergada měla přehled o tom, co se v aplikaci kdy a jak změnilo.
    • V editoru “poznámek v vydání” lze používat Markdown.
  • Přepracované zabezpečení hook requestů ze strany Mergada.

    • V minulosti se o autentizaci hook requestů staral samotný Appcloud. Ten - pro vývojáře zcela transparentně - kontroloval, zda požadavky z Mergada obsahují správnou hodnotu speciální HTTP hlavičky. Pokud request na URL, kde appka přijímala hooky (.../_mergado/hook/), neobsahoval správnou hodnotu příslušné hlavičky, požadavek server vůbec nepustil dál. Protože nově appky mohou sídlit i jinde, než na Appcloudu, tento magický mechanismus se musel přepracovat a zjednodušit.
    • Nově se o autentizaci hook requestů musí starat samotná appka (resp. její vývojáři).
    • Jak to funguje:
      • Každá stage appky má vlastní náhodně vygenerovaný a tajný klíč, tedy Webhook Secret. Tento klíč je k dispozici u appky v Developers.
      • Daný klíč zná jen Mergado a vývojáři appky.
      • Mergado tento klíč posílá v HTTP hlavičce Mergado-Apps-Webhook-Secret u všech requestů, které na appku míří - tj. všechny požadavky na hook endpoint a na endpointy pravidel aplikace.
      • Aplikace by při přijímání requestů na těchto endpointech měla kontrolovat správnou hodnotu tajného klíče - a odmítnout ty požadavky, které ji neobsahují.
      • Takto je zabráněno neoprávněným requestům od třetích stran.
  • Nový hook ping, kterým se v Developers dá jednoduše otestovat funkčnost hook endpointu aplikace.

    • U appky na stránce Přehled v Developers jsou dvě nová tlačítka (pro každou stage jedno), kterým se na hook endpoint appky dá odeslat testovací hook (POST request) v tomto formátu:

      {
      	"action": "ping"
      }
      

      Pokud se na tento request vrátí odpověď ve formátu …

      {
      	"message": "pong"
      }
      

      … považuje se hook za úspěšně vyřízený. Vrátí-li se cokoliv jiného, je to považováno za neúspěch. V obou případech se tento výsledek ihned zobrazí v UI.

  • Na Appcloudu je implementovaná možnost spouštět pre-release skript.

    • Tato možnost je k dispozici pouze v případě, že celý release appky probíhá v rámci Appcloudu. To znamená, že aby se pre-release spouštěl, musí obě stage appky musí jako úložiště používat Appcloud.
    • Jak to funguje:
      • Vývojová verze appky v rootu svého zdrojového kódu (např. /srv/production/apps/app_logbook.dev/app/) může obsahovat soubor s názvem mergado_pre_release.
      • Tento soubor se před přepsáním produkční verze verzí vývojovou zkopíruje do root adresáře se zdrojovým kódu produkční verze (např. /srv/production/apps/app_logbook/app/).
      • Zde se soubor spustí, pod uživatelem produkční verze appky. Respektuje se shebang, takže tento skript může být napsaný jak v bashi, tak třeba i v PHP.
      • Release pokračuje až po skončení tohoto skriptu (bez ohledu na výsledek). Pokud tento skript neskončí do jedné hodiny, ukončí se, výsledek se ignoruje a release pokračuje dál.
  • V Developers je nově k dispozici :uk: anglická jazyková verze Mergado Store banneru.

  • Aplikace lze nově označit jako “deprecated”.

    • U “deprecated” appky bude na její stránce v Mergado Store vidět hláška, že již není ve vývoji.
    • Lze nastavit jinou appku, jakožto nástupce, na kterou se u dané hlášky v Mergado Store bude odkazovat.
    • Je to marketing-friendly alternativa k úplnému smazání aplikace.
    • Je k tomu potřeba kontaktovat podporu Mergada.

#23

:ice_cream: Mergado Apps 0.3.19

Release date

18. červenec 2018

Změny

  • MQL má nové operátory CONTAINS a NOT CONTAINS.
    • Příklad:
      {
      	"name": "Product has CZ country in square brackets",
      	"query": "[PRODUCT] CONTAINS \"[cz]\"",
      	"read_only": false,
      	"search_output": true
      }	
      
    • Tyto operátory doplňují původní regulární operátory ~ a !~, které by u výše uvedeného příkladu pravou stranu interpretovaly nikoliv jako čistý text, nýbrž (chybně) jako regulární výraz (buď znak “c” a nebo znak “z”).
  • Pravidlo nastavení dopravy nyní správně vytváří element PRICE_COD pro formát Favi.cz, Favi.sk a Favi.ro.
  • Opravena chyba, kdy převodník na Zboží.cz pomíchával pořadí elementů s obrázky.
  • Opravena chyba, kde Google/Facebook převodník špatně vyplňoval měnu.

#24

:pretzel: Mergado Apps 2.0

Release date

22. srpen 2018

Změny

Vydáváme Mergado API v nové major verzi 2.0.
API je nyní verzováno. V hlavičce Accept je možné zadat požadovanou verzi API, a to v této podobě:

application/mergado-v2+json

Pokud není vyžádána konkrétní verze, použije se výchozí (tj. verze 1). Veškeré změny vycházející z této nové verze jsou sepsány níže.

Změny ve staré verzi Mergado API

  • Endpointy /stats/audits/<id>/ a /stats/audits/<id>/issues statistických auditů mohou obsahovat nový verdict missing_stats.

    • Použije se, pokud ve statistikách chybí hodnota potřebná pro validaci. Např. validátor heureka_price_status vyžaduje hodnotu min_price_2, která však chybí v sortiment reportu z Heureky, pokud produkt prodává jen jeden eshop.
  • Endpointy /products/<id>/stats/ a /projects/<id>/stats/products/ a /shops/<id>/stats/products/:

    • Pole stats.price, stats.heureka_is_alone, stats.heureka_cpc_status, stats.heureka_is_paired, stats.heureka_margin_status, stats.heureka_price_status, stats.heureka_position_status a stats.heureka_profit vždy vrací null (pro zachování alespoň částečné zpětné kompatibility).
    • Přidáno pole heureka_id, které odpovídá poli product_id ze sortiment reportu Heureky.

Změny v Mergado API v2.0

  • Endpointy /shops/<id>/statslogs/ a /statslogs/<id>/

    • Nový typ logů audit nahradil původní typ report.
  • Endpoint /products/<id>/stats/

    • Nově vrací historii statistik (původně vracel statistiky pro jeden den) - vrací se tedy kolekce (seznam) místo jednoho záznamu.
      • Pokud se v URL zašle parametr date, vrátí seznam o jednom prvku, kterým jsou statistiky pro zadaný den.
      • Jinak je možné specifikovat start_date a end_date.
      • Pokud není specifikováno nic, použije se výchozí start_date (měsíc nazpět) a end_date (včerejšek).
    • Úpravy polí:
      • Přidáno pole heureka_id, které odpovídá poli product_id ze sortiment reportu Heureky.
      • Odstraněná pole:
        • price
        • heureka_is_alone
        • heureka_cpc_status
        • heureka_is_paired
        • heureka_margin_status
        • heureka_price_status
        • heureka_position_status
        • heureka_profit
      • Přejmenovaná pole:
        • categorytext :arrow_right: heureka_categorytext
        • delivery_date :arrow_right: heureka_delivery_date
        • heureka_cpc :arrow_right: heureka_feed_cpc
        • heureka_stats_clicks :arrow_right: heureka_clicks
        • heureka_stats_cost_of_sales :arrow_right: heureka_cost_of_sales
        • heureka_stats_cpc :arrow_right: heureka_cpc
        • heureka_stats_sales :arrow_right: heureka_sales
        • heureka_stats_total_cost :arrow_right: heureka_total_cost
        • heureka_stats_total_orders :arrow_right: heureka_total_orders
        • imgurl :arrow_right: heureka_imgurl
        • manufacturer :arrow_right: heureka_manufacturer
        • url :arrow_right: heureka_shop_url
        • heureka_name :arrow_right: heureka_card_name
        • price_vat :arrow_right: heureka_price_vat
        • name :arrow_right: heureka_name
      • Polím cost, is_starter a is_topseller byl přidán prefix mergado_:
        • cost :arrow_right: mergado_cost
        • is_starter :arrow_right: mergado_is_starter
        • is_topseller :arrow_right: mergado_is_topseller
      • Přidána pole Zboží.cz CVS reportu:
        • zbozi_conversion_cost_czk
        • zbozi_conversion_cost_czk_product_detail
        • zbozi_conversion_cost_czk_category_search
        • zbozi_conversion_cost_czk_top_product_detail
        • zbozi_conversion_cost_czk_category_listing
        • zbozi_conversion_cost_czk_search_result
        • zbozi_cpc_czk_product_detail
        • zbozi_cpc_czk_category_search
        • zbozi_cpc_czk_top_product_detail
        • zbozi_cpc_czk_category_listing
        • zbozi_cpc_czk_search_result
        • zbozi_cpc_czk_vat_product_detail
        • zbozi_cpc_czk_vat_category_search
        • zbozi_cpc_czk_vat_top_product_detail
        • zbozi_cpc_czk_vat_category_listing
        • zbozi_cpc_czk_vat_search_result
        • zbozi_conversions_value_czk_product_detail
        • zbozi_conversions_value_czk_category_search
        • zbozi_conversions_value_czk_top_product_detail
        • zbozi_conversions_value_czk_category_listing
        • zbozi_conversions_value_czk_search_result
        • zbozi_conversions_value_czk
        • zbozi_id
        • zbozi_name
        • zbozi_last_known_category
        • zbozi_conversion_rate_product_detail
        • zbozi_conversion_rate_category_search
        • zbozi_conversion_rate_top_product_detail
        • zbozi_conversion_rate_category_listing
        • zbozi_conversion_rate_search_result
        • zbozi_conversion_rate
        • zbozi_cpr_product_detail
        • zbozi_cpr_category_search
        • zbozi_cpr_top_product_detail
        • zbozi_cpr_category_listing
        • zbozi_cpr_search_result
        • zbozi_cpr
        • zbozi_conversions_product_detail
        • zbozi_conversions_category_search
        • zbozi_conversions_top_product_detail
        • zbozi_conversions_category_listing
        • zbozi_conversions_search_result
        • zbozi_conversions
        • zbozi_products_sold_through_zbozi
        • zbozi_direct_conversions
        • zbozi_card_name
        • zbozi_bid_click_through_product_detail
        • zbozi_bid_click_through_category_search
        • zbozi_bid_click_through_top_product_detail
        • zbozi_bid_click_through_category_listing
        • zbozi_bid_click_through_search_result
        • zbozi_bid_click_through
        • zbozi_avg_position_product_detail
        • zbozi_avg_position_top_product_detail
        • zbozi_views_product_detail
        • zbozi_views_category_search
        • zbozi_views_top_product_detail
        • zbozi_views_category_listing
        • zbozi_views_search_results
      • Dále přidána pole z feedu Zboží.cz:
        • zbozi_delivery_date
        • zbozi_categorytext
        • zbozi_max_cpc
        • zbozi_max_cpc_search
        • zbozi_manufacturer
        • zbozi_brand
        • zbozi_shop_url
        • zbozi_imgurl
        • zbozi_price_vat
  • Endpointy /projects/<id>/stats/products/ a /shops/<id>/stats/products/:

    • Stejné změny jako u /products/<id>/stats/.
  • Endpoint /shops/<id>/info/:

    • mergado.output_feed :arrow_right: mergado.output_feed_heureka.
    • mergado.report :arrow_right: mergado.audit.
    • Přidány typy mergado.output_feed_zbozi a zbozi.product_stats_report.

#25

:moneybag: Mergado Apps 2.0.1

Release date

  1. listopdadu 2018

Změny v API

  • Endpointy, které vrací pole entit, budou kromě offset a limit obsahovat total_results, což je celkový počet entit, který odpovídá danému požadavku.
  • Do statistik produktů byl přidán field heureka_actual_cpc, který odpovídá hodnotě elememtnu CPC z Heurekovského sortiment reportu.