Tässä dokumentissa kuvataan tapa, jolla Johku-kaupan tuoteryhmiä ja tuotteita voi helposti näyttää osana verkkosivustoja. Julkaisujärjestelmien tapauksessa tämä yleensä tarkoittaa jonkinlaisen pluginin rakentamista.  


Toimintatapa


Johku-palvelimelta haetaan tuotelistaus JSON-muodossa. Haku voidaan tehdä joko pluginilla yksittäisen sivun/sivukehyksen sisälle tai julkaisujärjestelmään syvemmin integroituna, jolloin sivuston rakennetta voi rakentaa haetun tiedon pohjalta. Haettu data käsitellään ja esitetään muodossa. Sivuille tulee liittää myös JSON-tiedon mukana toimitettava Javascript-pohjainen upotuskoodi, joka sisältää tuotteen tyyppikohtaiset ostotoiminnallisuudet ilman, että niitä tarvitsee erikseen ohjelmoida.  Tämän lisäksi sivuston kaikille sivuille on liitettävä ostoskorin upotuskoodi, jonka parametreilla määritellään ne kaupat joiden tuotteita sivustolla ristiinmyydään. Upotteen ja tuote- ja ostoskorinäkymien tyylit määritellään CSS:llä sivuston ulkoasua vastaaviksi.



Tuotelistaukset tuoteryhmittäin


Johkussa tuotteiden ryhmittely listauksia varten tehdään Tuoteryhmien kautta.  Sama tuote voi olla useammassa kuin yhdessä tuoteryhmässä. JSON-listauksissa näytetään samat tuotteet ja tuoteryhmät kuin ne, jotka on määritelty näytettäväksi Johkun omalla kauppapaikalla. Tuoteryhmään liitetyt tuotteet saadaan haettua seuraavankaltaisella HTTP GET-kutsulla:


https://johku.com/tervarumpu/fi_FI/categories/9/allproducts.json?details=true&version=fi_FI&locale=fi_FI


Tässä “tervarumpu” on kaupan tunnus, "9" on haettavan tuoteryhmän id-numero ja  “fi_FI” on valittu kieli.


Normaalisti sivustolle integroitaessa haetaan kiinteästi määritellyt tuoteryhmät halutuille sivuille, eli käytetään manuaalisesti määritettäviä tuoteryhmien id-numeroita. Jos halutaan hakea tuoteryhmätkin dynaamisesti, onnistuu se haulla:


https://johku.com/tervarumpu/fi_FI/categories.json?version=fi_FI&locale=fi_FI


Vastauksena tulevasta listauksesta voidaan käyttää sellaisia tuoteryhmiä, joiden enable_catalog -arvo on 1.


Haut eivät edellytä mitään autentikointia, koska kaikki vastauksessa näytettävät tuotetiedot ovat julkisia. Vastauksena tuleva data sisältää kaikki tuotteen sivustolla näyttämiseen tarvittavat tietokentät. Tietokenttiä voi tulla aikaa myöten lisää.




Tietokentät


Tuoteryhmän listaushaussa ylin taso sisältää tuoteryhmän kannalta tärkeitä mutta sivustointegraation kannalta vähemmän oleellista tietoa. Sen sijaan kunkin listatun olion sisältä löytyvä "product" on kiinnostava, ja sen sisältä löytyykin kyseisen tuotteen kaikki tarvittava tieto. Tuoteryhmän listauksen luontiin on Jalusta-integraatioissa käytetty tuoteryhmähakutuloksen kunkin tuotteen aineistossa olevista product-kentän sisällä olevista tietokentistä seuraavia:



id = tuotteen id-numero Johkussa

marketingname = tuotteen markkinointinimi, jos sellainen on erikseen määritetty - tätä tulee käyttää

name = tuotteen normaali nimi - tätä tulee käyttää vain jos marketingname -arvoa ei ole

description = tuotteen lyhyempi kuvausteksti

buttontext = tuotteen ostopainikkeelle määritelty teksti, jos tekstiä ei ole määritelty on käytettävä jotain muuta tekstiä (Johku ei anna tälle oletusarvoa)


price = hinta ilman valuuttatunnusta

vat = alv-prosentti, esim 24

type = tuotteen päätyyppi

1: myytävä tuote

2: varattava tuote


subtype = varattavan tuotteen tarkempi määrittely

0: varattava tuote (perustyyppi)

1: vuokrattava majoitus

2: aktiviteeetti

3: kuljetus

4: tapahtuma (elokuva, konsertti jne)

5: lippu


displayedtype = varattavan tuotteen vielä tarkempi määrittely, joka yhdessä subtypen kanssa kertoo mistä tuotteesta oikeasti on kyse. 

generic: kunkin subtypen perusarvo

muut arvot kertovat jo nimellään pitkälti sen, mitä ne tarkoittavat

warehouse_count = ostettavan tuotteen varastosaldo

multiple_prices = 1, jos listattu hinta voi vaihtua ja tämä olisi listoissa indikoitava (esim. "alkaen")

product_unit = hinnoittelun yksikkö varattavilla tuotteilla tai aktiviteeteilla kesto)

unit_type (hinnoittelun yksikön tyyppi varattavilla tuotteilla ja aktiviteeteilla, 1 = minuutteja, 2 = tunteja, 3 = päiviä)


hide_units = 1, jos tulisi näyttää vain hinta ilman yksikköä (esim. 20 euroa vs. 20 euroa / 2h)

hide_pricing = 1, jos hinnoittelu tulisi kokonaan piilottaa listauksesta


companyname (tuotetta myyvä kauppias, hyödyllinen jos on useita yrityksiä samalla sivustolla)

file_id = tuotteen pääkuvan id, jos kuvaa ylipäänsä on, file_ext = tuotteen pääkuvan tiedostopääte)

tuotteen pääkuvan osoitteen saa näistä muodostettua seuraavasti:

https://www.johku.com/kaupantunnus/files/file_id.file_ext 


sharedProduct  = tuotteeseen linkitettyjen lisämyytävien tuotteiden tiedot JSON-muodossa (jos halutaan listata myös lisämyytäviä tuotteita tuotteen sivulla)

sharedTag = kaikki tuotteeseen määritellyt tagit

embedcode = ostologiikan upotuskoodi

basketembedcode = ostoskorin upotuskoodi




Yksittäisen tuotteen tuotesivun luomiseen on kaksi tietä. Toteutustavaltaan helpoin mutta räätälöintimahdollisuuksiltaan rajatuin tapa on käyttää “largeembedhtml” -kentän sisältöä, joka sisältää tarvittavan html-koodin tuotetietoineen, sekä “largeembedcode”-kentästä löytyvä script-tagia, joka luo ostotoiminnallisuuden tätä html-rakennetta hyväksikäyttäen. 


Työläämpi, mutta lopputulokseltaan hallitumpi tie on käyttää datasta yksitellen löytyviä arvoja ja "embedcode" -kentästä löytyvän pelkän ostologiikan sisältävän upotteen pohjalta luotua koodia (koodin fields-listalla on oletuksena ne arvot, jotka Johkussa on määritelty kullekin tuotteelle erikseen, mutta integroitaessa tälle fields-listalle ei tarvitse jättää muuta kuin hinta eli "price" ja painikkeen teksti)


<script type="text/javascript" src="https://johku.com/embed/?shopId=kaupantunnus&productId=122&fields=price&buttonText=Osta">


Tämä upotuskoodi tulee sitten sijoittaa sivun html-koodiin siihen, mihin ostotoiminto halutaan sijoittaa, ja tämän lisäksi se tulee kustomoida CSS-tyyleillä sivuston ilmeeseen sopivaksi (selainten kehittäjätyökalut kuten Chromen Inspector auttavat oikeiden tyylien löytämisessä ja yliajamisessa).


Lisäksi jokaiselle sivuston sivulle, jolla halutaan näyttää ostoskori, täytyy liittää ostoskorin upotuskoodin script-tagi, joka puolestaan löytyy “basketembedcode”-kentästä ja on sama joka paikassa.



Elokuvat ja niiden listaaminen


Elokuvalistauksen rajapinnat ovat vielä kehityksessä ja tulevat muuttumaan ja kehittymään. Tässä vaiheessa käyttössä on edellä kuvattuja tuotetietoja elokuvien osalta listaava näytösajat-listaus.


https://johku.com/kaupantunnus/showschedule.json?details=true&version=fi_FI&language=fi_FI


Tämä listaus näyttää kaikki kalenteriin merkityt näytökset. Listausta voi haettaessa rajata "from" ja "to" parametreilla annettavilla VVVV-KK-PP -päivämäärillä (https://johku.com/kaupantunnus/showschedule.json?details=true)


Tuotelistauksesta poiketen aikataululistassa on syytä tarkastella product-kentän eli varsinaisen elokuvan alta löytyvien kenttien lisäksi myös muita kunkin näytöksen päätason kenttiä. Esimerkiksi "resource_name" sisältää näytöksen salin nimen ja "pricing_name" -kenttää voi käyttää elokuvan tyypin ja sitä kautta hinnoittelun selventämiseksi (esim. "Lastenelokuva")


Kentät "agelimit" ja "attributes" ovat ikäraja ja sisältömerkintöjä varten. Ikäraja on tekstimuodossa "K-12" jne, ja attributes -kentän alta löytyy "violent", sexual", "disturbing" ja "drugs", jotka ollessaan arvoltaan true kertovat elokuvan sisältävän teemoja "Väkivalta", "Seksi" "Ahdistus" tai "Päihteet"


Muut kentät selittänevät nimellään tarkoituksensa. Jälleen kerran tuotelistauksesta avauttavalle tuotesivulle tulee haluttujen tietojen lisäksi laittaa tuotteen "embedcode"-kentän kautta annettu ostotoiminto-upotus.Upotuksesta ollaan parhaillaan kehittämässä pelkät näytösajat minimaalisella html-rakenteella sisältävää versiota, joka tulee omassa kentässään (todennäköisesti "scheduleembedcode). Koodi on tällä hetkellä seuraavanlainen:


<script type="text/javascript" src="https://johku.com/embed/?shopId=kaupantunnus&productId=122&view=schedule">


Esimerkkitiedosto on liitteenä.



Yksittäisen tuotteen tiedot


Joissain tilanteissa - mm. silloin jos halutaan avata tuotesivu sellaiselle tuotteelle, joka on toisen tuotteen lisämyytävä tuote - sen tietoja ei ole vielä haettu categories-tuoteryhmähaussa. Tällöin se on haettava erikseen tuotteen tietojen rajapinnasta:


https://johku.com/tervarumpu/fi_FI/products/77.json?externalembed=true&version=fi_FI&locale=fi_FI


Jossa "tervarumpu" on kaupantunnus ja "77" halutun tuotteen id-numero.



Muita huomioita


Johkusta ladattava tuotelistausten JSON-data kannattaa kehitysvaiheen jälkeen laittaa tallentumaan välimuistiin. Suositeltava päivitystiheys on tunti. Tällä varmistetaan, että sivuston lataus ei turhaan hidastu Johkusta tehtävien hakujen takia sekä vähennetään Johkuun tulevaa tarpeetonta liikennettä. Tällöin tietokenttiin syötetyt tiedot päivittyvät enintään tunnin viiveellä, mutta saatavuustiedot päivittyvät silti reaaliaikaisesti. Näytösajoissa välimuisti voi olla lyhyempikestoinen.