Tämä dokumentaatio esittelee Big Bamboo Slot -kolikkopelin API:n ohjelmoijille ja teknologia-kumppaneille. API sallii pelin upottamisen ja hallinnoinnin kolmannen osapuolen alustoissa. Olemme huolellisesti suunnitelleet tämän oppaan Suomen markkinoiden markkinoiden vaatimuksiin, huomioiden kansalliset järjestelmästandardit, säädösvaatimukset ja vakiintuneet integraatiokäytännöt. Käyttöön antamamme API perustuu REST-arkkitehtuuriin ja hyödyntää JSON-muotoista tietoa, mikä nopeuttaa sen implementointia. Tästä kyseisestä tekstistä näet keskeiset määritelmät, turvallisuusmekanismit, tunnistautumisen ja tavallisimmat skenaariot, jotta kykenet panna alulle yhdistämisesi varmasti.

Johdanto Big Bamboo Slot -rajapintaan

Big Bamboo Slot -rajapinta tarjoaa muunneltavat ja varmat apuvälineet kolikkopelin kytkemiseksi verkkosivuille, mobiilisovelluksiin tai muihin pelialustoihin. Kaikki operaatiot tapahtuvat standardoitujen HTTP-pyyntöjen, kuten GET, POST ja PUT, kautta. Tämä REST-pohjainen tapa aiheuttaa rajapinnasta kieliriippumattoman, ja se yhteensopii useimpien nykyaikaisten ohjelmointikehysten kanssa. Suunnittelimme ratkaisun noudattaen Suomen tiukkoja tietosuoja- ja rahapelilakeja. Tietojen siirrossa sovelletaan salausmenetelmiä, ja pelaajan henkilötiedot käsitellään turvallisesti. Tarjoamme myös täyden testiympäristön (sandbox), jossa voit luoda ja kokeilla integraatiota ilman oikeaa rahaliikennettä. Tämä helpottaa kehitysvaiheen vianetsintää huomattavasti.

Parhaat käytännöt suorituskyvyn optimoimiseksi

Jotta integraatiosi olisi vauhdikas ja luotettava, noudata muutamaa peruskäytäntöä. Neuvomme toteuttamaan välimuististrategian niille API-kutsuille, jotka eivät sisällä kriittistä reaaliaikadataa. Tällaisia ovat kuten pelin staattiset asetustiedot tai automaattisesti vanhentuvat mainokset. Välimuisti vähentää tarpeettomia verkkopyyntöjä ja nopeuttaa sivustosi latautumista. Toinen keskeinen tekijä on yhteyksien hallinta. Ota käyttöön HTTP-pysyvää yhteystapaa (keep-alive). Se välttää toistuvan TCP-yhteyden muodostamisen aiheuttaman ylimääräisen kuorman. Vaikka API-mme on suunniteltu kestämään kuormitusta, suunnittele asiakaspuolesi koodi käsittelemään mahdollisia viiveitä tai väliaikaisia virhetilanteita. Sujuva tapa on käyttää eksponentiaalista backoff-uudelleenyritysstrategiaa keskeisissä toiminnoissa.

Suorituskyvyn kannalta on suositeltavaa minimoida samanaikaisten API-kutsujen määrä yhdellä sivulla. Sen sijaan, Bigbambooslot, että tekisit useita erillisiä kutsuja pelaajan saldolle, pelitilalle ja kampanjatiedoille, harkitse oman backend-palvelimesi käyttöä. Se voi kerätä nämä tiedot yhdellä kutsulla meiltä ja palvella ne asiakkaallesi yhdistetyssä muodossa. Lopuksi, seuraa aktiivisesti integraatiosi suorituskykyä tuotannossa. Annamme mahdollisuuden saada tilastotietoja API-käytöstäsi kehittäjäportaalissamme. Nähtävillä on tietoja kuten pyyntömääriä, keskimääräistä vasteaikaa ja virhemääriä. Näiden tietojen avulla voit tunnistaa trendejä ennen kuin ne muodostuvat ongelmiksi.

Kehitysympäristö ja kehityksen vinkit

Ennen kuin siirrä integraatiosi tuotantoon, testaa sitä perusteellisesti tarkoitukseen varatussa testausympäristössämme (sandbox). Tämä ympäristö on täydellisesti erillään tuotannosta. Se käyttää pelirahaa, joten voit jäljitellä eri pelimekaniikkoja ja rahaliikenteen käsittelyä ilman mitään todellisia taloudellisia riskejä. Testiympäristön API-avaimet eroavat tuotantoavaimista. Noudat ne ilmoittautumalla kehittäjäportaaliimme. Kehotamme testaamaan varsinkin seuraavia skenaarioita: epäonnistunut verkkovastaus kesken talletuksen, pelaajan yhteyden katkeaminen pelin aikana, eri voittotilanteiden hoito ja maksimibet-rajojen testaus. Tämä mahdollistaa varmistamaan, että integraatiosi on luotettava ja tarjoaa varman kokemuksen poikkeustilanteissakin.

• Ota käyttöön lokitusta: Tee laaja lokitus kaikista API-kutsuistasi, sekä onnistuneista kuin epäonnistuneista. Se on välttämätön apuväline vianetsinnässä.
• Jäljittele hidasta verkkoa: Kokeile, miten järjestelmäsi reagoi, mikäli API-vastaus tulee hitaasti. Käytä timeout- ja uudelleenyritysmekanismeja.
• Tarkasta lakisääteiset vaatimukset: Varmista, että integraatiosi täyttää vaatimukset jokainen Suomen rahapelilainsäädännön asettamat velvoitteet. Nämä pitävät sisällään ikävähennyksen ja peliongelmaresurssien saatavuuden.
• Tee kantatestaus: Pyydä kolmatta osapuolta, kuten kollegaasi, testaamaan integraatiota ulkopuolisesta näkökulmasta. He saattavat huomata käytettävyysongelmia, jotka sinulta jäi huomaamatta.

Autentikointi ja suojaus

Suojaus on ensimmäisenä jokaisessa toiminnassamme. Tämä asia koskee varsinkin Suomen markkina-alueita, joilla vaatimukset ovat tiukat. Kaikki tuotantoympäristöjen API-kutsut vaativat salatun salatun HTTPS-yhteyden. Varmennus pohjautuu JWT (JSON Web Token) -määrittelyyn. Se antaa vankan ja skaalattavan menetelmän todentaa kyselyjen todellisuus. Saat yksilöllisen API-avaimen sekä salasanan kirjautumisen päätteeksi. Näitä tietoja käytetään JWT-tokenin luomiseen. Tämä token asetetaan tämän jälkeen Authorization-kenttään joka seuraavassa API-kutsussa. Suosittelemme uudistamaan API-salaisuuttasi säännöllisesti. Älä ikinä tallenna kyseistä asiakasohjelman skriptissä tai Git-varastossa. Jokainen persoonatietoja ynnä maksuliikennettä käsittävät tieto suojataan apuna varmoja menetelmiä siirtämisen aikana.

JWT-avainten soveltaminen

JWT-token on kryptografisesti allekirjoitettu, sekä joka kattaa tarpeelliset lausumat (claims) käyttäjästäsi sekä hänen valtuuksistaan. Tunnus on tavallisesti voimassa määräaikaisen aikaa, minkä jälkeen tämä täytyy uusia. Olemme toteuttaneet systeemin siten, että suojatut, vaikka toistuvasti toistuvasti pyydetyt funktiot, kuten pelitilanne haku, pystyvät hyödyntää pidempiaikaisia validiteettiaikoja. Rahaliikenteeseen yhdistyvät funktiot tarvitsevat lyhyitä ynnä tiheämmin uudistettavia tokeneita. Tämä sovittaa yhteen käytettävyyttä ja suojaa. Tarjoamme lisäksi oman päätepisteen tunnuksen uudistamiseen niin, ettei asiakkaan täytyy logata sisään kerran uudestaan. On tärkeää, jotta toteutat tunnuksen hallintatehtävien selaimellasi turvallisella tavalla. Vältä tämän paljastuminen ulkopuolisille tahoille.

Ohjelmointirajapinnan perusrakenteen hahmottaminen

Big Bamboo Slot API:n rakenne on suoraviivainen. Oliot, kuten pelikerta, pelaajatiedot ja pelitapahtumat, ovat saatavissa uniikeilla URI-osoitteillaan. Hyväksytty pyyntö antaa HTTP-statuskoodin 200-sarjasta ja vastausaineistoa JSON-muodossa. Virheiden sattuessa annamme selittävät virhetunnukset ja kuvaukset, jotta voit havaitsemaan virheen välittömästi. Rajapinta tukee monipuolista hakutoimintoa monille toiminnoille, kuten siirtohistorialle. Tällä tavalla kykenet rajata tuloksia päivämäärän, rajoituksen tai jonkin ehdon mukaan. Tämä johdonmukainen arkkitehtuuri parantaa kehittäjäkokemusta ja järjestelmän huollettavuutta.

Endpointit (Endpoints) ja Tietokohteet

Keskeisimmät päätepisteet liittyvät pelisession käynnistämiseen, pelaajan tietojen noutamiseen ja peliaktiviteettien tallentamiseen. Uusi pelikerta muodostetaan laatimalla POST-pyyntö sopivaan osoitteeseen. Vastauksena saat yksilöllisen kerran ID:n ja peliin yhdistymisen edellyttämän URL-osoitteen. Toinen tärkeä päätepiste huolehtii pelaajan saldon tahdistuksesta. Kyseinen tarkistaa, että näytettävä saldo on jatkuvasti tuore eikä pelaaja ylitä sille määritettyjä rajoituksia. Kaikissa rahoitusliikenteeseen kytkeytyvissä päätepisteissä sovellamme idempotenssiavaimea. Tämä avain ehkäisee saman transaktion haitallisen toistolähetyksen, mikä on kriittistä taloudellisten toimenpiteiden kokonaisuudelle.

Vastauskoodit ja Virheenkäsittely

Olemme luoneet yksiselitteisen virhehallintajärjestelmän. Jokainen vastaus käsittää lukuarvoisen tilatunnuksen ja ihmisluettavan selityksen. Esimerkkinä koodi 400 ilmaisee, että kyselyssä oli virhe, kuten puuttuva pakollinen kenttä. Koodi 401 merkitsee epäonnistunutta kirjautumista. Kehotamme toteuttamaan kattavan virheidenkäsittelyn asiakaspuolellasi näiden koodien perusteella. Tällä tavoin UX säilyy hyvänä myös yllättävissä tilanteissa. Annamme myös endpointit huollon aikatauluille ja järjestelmän tilalle. Näiden kautta kykenet ennakoida potentiaalisia katkoksia ja tiedottaa asiakkaitasi etukäteen. Tämä selkeys on tärkeää loppukäyttäjien uskollisuuden rakentamisessa.

Suomen lakien huomioon ottaminen

Suomen rahapelilainsäädäntö (Rahapelilaki 104/2001) antaa yksiselitteisiä vaatimuksia kaikenlaisille pelitoimijoille. Nämä vaikuttavat välittömästi API-integraatioon. Yksi oleellisimmista vaatimuksista on iän tarkistus. Se takaa, että vain aikuiset henkilöt voivat pelaamaan. Liittymäsi on kyettävä toimittamaan pelaajan ikätieto varmasti alustallemme ennen pelisession avaamista. Seuraava oleellinen vaatimus koskee peliongelmaisten suojaa. Meillä on tarjottava yksinkertaiset työkalut peliajan ja tappioiden rajoittamiseen sekä ilmoitettava avun saannista. API-mme tarjoaa päätepisteet, joiden avulla voit hakea ja asettaa pelaajan itsensä valitsemia rajoja. Voit myös kuvata nämä rajat pelaajalle sivustollasi. Jokainen pelitapahtumat on tallennettava ja saatavissa vähintään 12 kuukauden ajan tilitystä varten.

Myös maksupalveludirektiivi (PSD2) ja vahva asiakastunnistus (SCA) koskettavat talletus- ja kotiutusprosesseihin. Vaikka nämä prosessit suoritetaan tyypillisesti maksupalveluntarjoajan kautta, on tärkeää, että API-integraatiosi sallii näiden säädösten tarvitsemaa turvallisuustasoa. Se edellyttää samoin tarvittavaa tietojen vaihtoa. Ehdotamme tutustumaan Suomen rahapeliviranomaisen, Pelivalvonnan, laatimiin ohjeisiin. Varmista, että koko pelikokemuksesi – mihin API-integraatio sisältyy keskeisenä osana – on vaatimusten kaltainen. Järjestämme konsultaatiota parhaista käytännöistä säädösten noudattamiseksi. Ole meihin yhteyttä, jos sinulla on kysyttävää.

Tärkeimmät API-kutsut ja niiden toteutustapa

Tämän jälkeen esitellään keskeisimmät API-kutsut, jotka tarvitaan pelin katkeamattomaan integrointiin. Joka kutsu vaatii asianmukaisesti muodostetun JWT-tunnuksen ja lähetetään määriteltyyn päätepisteeseen. Alla ovat keskeisimmät vaiheet, joiden kautta onnistut pelin toimimaan ympäristössäsi.

1. Käyttäjän tunnistaminen ja sessio: Ensimmäiseksi tarkistat pelaajan henkilöllisyyden ja tilan järjestelmässämme. Tämä toteutetaan käyttämällä pelaajan uniikkia tunnistetta.
2. Pelikerran luominen: Tämän jälkeen teet uuden pelisession, joka yhdistää pelaajan määrättyyn pelikertaan. Saatte vastauksena vastauksena ainutlaatuisen session tunnuksen.
3. Pelin käynnistäminen: Hankittuja tietoja hyödyntäen johdat pelaajan välittömästi peliin tai näytät pelin iframeen omalle sivustollesi.
4. Saldon synkronointi: Teidän on noudettava ja täydennettävä pelaajan saldoa säännöllisesti reaaliajassa. Käytä tässä erillistä päätepistettä.
5. Kierroksen lopputuloksen raportointi: Kun pelikierros on ohi, ilmoitat lopputuloksen palautteena järjestelmäämme toimintojen kirjaamista varten.

Joka näistä vaiheista on välttämätön. Niiden oikea suorittaminen varmistaa että pelaaja voi pelata sulavasti, hänen rahansa hoidetaan oikein ja kaikenlaiset pelitapahtumat ovat läpinäkyviä. Annamme kullekin vaiheelle tarkat esimerkkipyynnöt ja -vastaukset kehittäjäportaalissamme. Pystyt testata toimintaasi askel askeleelta niiden avulla. Ota huomioon samoin, jos jos pelaaja siirtyy pois pelistä keskellä kierroksen, kehittäjän on osattava siirtämään hänet alkuperäiseen tilaan. Tämä toimii tallessa olevan session tunnuksen avulla, kun hän hän palaa.

Päätelmät ja tulevat askeleet

Big Bamboo Slot API antaa Suomen kehittäjille apuvälineet, joilla luodaan laadukas ja lakisääteisten vaatimusten mukainen pelikokemus. Lähde liikkeelle rekisteröitymällä kehittäjäportaaliimme. Sieltä saat pääsyn täydelliseen API-dokumentaatioon, testiavaimet ja hallintapaneelin integraatiosi tarkkailuun. Suosittelemme uhraamaan aikaa testausympäristössämme. Testiympäristössä kykenet perehtymään kaikkiin toimintoihin ilman vaaroja. Olemme täällä avustamassa sinua koko matkan ajan. Älä epäröi kysyä tekniseen tukeemme, jos törmäät ongelmia tai sinulla on ehdotuksia integraatiosi viimeistelemiseksi. Yhdessä pystymme tarjota Suomen pelaajille turvallisen, hauskan ja sujuvan pelikokemuksen.