Kehittäjän viiteopas

Lyhyt viiteopas kehittäjille: tagi ja sen attribuutit, JavaScript-rajapinta, mitä paneeli tallentaa, mitä se lataa ja rivit tiukkaa Content-Security-Policyä varten.

Tagi

<script async src="https://oma.lanetti.fi/embed/accessiboss.js" data-key="abs_site_avaimesi"></script>

Attribuutti	Mitä se tekee
`data-key`	Pakollinen. Sivuston julkinen avain Asennus-osiosta. Ei salaisuus.
`async`	Pidä mukana. Silloin tagi ei koskaan pysäytä sivun jäsentämistä eikä latautumista.
`data-locale`	Valinnainen. Pakottaa paneelin kielen, esimerkiksi `fi`. Ilman sitä paneeli seuraa Studion asetusta, sitten sivun `lang`-määritettä ja sitten selainta.
`nonce` tai `data-nonce`	Valinnainen. Nonceen perustuvaa käytäntöä varten. Tagin lisäämät tiedostot ja tyylit saavat saman noncen.

Tagin lisääminen kahdesti ei tee mitään ylimääräistä. Tagi ei koskaan heitä virhettä sivullesi: jos jokin epäonnistuu, paneeli jää pois ja sivusi toimii normaalisti.

Avaa paneeli omasta elementistä

Mikä tahansa elementti, jolla on data-accessiboss-open, avaa paneelin klikkauksella. Käytä oikeaa painiketta, jotta myös näppäimistön ja ruudunlukijan käyttäjät voivat käyttää sitä:

<button type="button" data-accessiboss-open>Näyttöasetukset</button>

Jos painike on Studiossa piilotettu jollakin laitteella, nämä elementit ovat ainoa tapa avata paneeli siellä.

JavaScript-rajapinta

Kun tagi on ajettu, window.Accessiboss sisältää neljä funktiota. Ne eivät palauta mitään.

Kutsu	Mitä se tekee
`Accessiboss.open()`	Avaa paneelin. Lataa tarvittaessa ensin paneelin koodin.
`Accessiboss.close()`	Sulkee paneelin. Kohdistus palaa siihen, missä se oli.
`Accessiboss.toggle()`	Avaa tai sulkee paneelin.
`Accessiboss.reset()`	Tyhjentää kävijän valinnat ja poistaa kaikki sivun muutokset.

Tagi latautuu async-määritteellä, joten tarkista ennen kutsua, että rajapinta on olemassa:

document.querySelector("#oma-saavutettavuuslinkki").addEventListener("click", () => {
  window.Accessiboss?.open();
});

Tapahtumat

Paneeli ei lähetä sivullesi tapahtumia, eikä kävijän valintoja voi lukea. Se on tarkoituksellista: kävijän valinnat pysyvät hänellä. Jos haluat reagoida kävijän tarpeisiin, käytä omassa CSS:ssäsi vakiomediakyselyjä, kuten prefers-reduced-motion ja prefers-contrast.

Mitä se tallentaa

Missä	Avain	Mitä
localStorage	`accessiboss:v1`	Kävijän valinnat, jotta ne ovat voimassa jo ennen kuin sivu piirtyy seuraavalla käynnillä.
localStorage	`accessiboss:v1:config:<avain>`	Kopio julkaistuista asetuksistasi. Käytetään heti ja päivitetään taustalla.
sessionStorage	`accessiboss:v1:hidden`	Kävijä piilotti painikkeen tämän selainistunnon ajaksi.

Ei evästeitä. Asetusten pyyntö lähetetään ilman tunnistetietoja.

Mitä se lataa

Tiedosto	Milloin
`accessiboss.js`	Sivun mukana. Ottaa tallennetut valinnat käyttöön ja hakee asetukset kolmen sekunnin aikarajalla.
`accessiboss-trigger.js`	Kun selain on joutilaana. Painike ja sen sijainti.
`accessiboss-panel.js`	Vasta kun joku osoittaa painiketta, kohdistaa siihen tai painaa sitä, tai kun tallennetut valinnat tarvitsevat sitä.
`accessiboss-locales/<kieli>.js`	Paneelin mukana muille kielille kuin englannille.
`accessiboss-fonts/*`	Vain kun kävijä valitsee helppolukuisen fontin.

Paneeli elää shadow rootissa <accessiboss-root>-elementissä <body>-osan ulkopuolella, joten CSS:si ei ulotu siihen eikä sen CSS valu sivullesi. Jos sovelluskehys korvaa bodyn, paneeli palauttaa itsensä.

Vain luku -rajapinta (Scale ja Agency)

Lue sivustosi, tarkistukset ja ongelmat omista työkaluistasi. Rajapinta vain lukee eikä muuta mitään. Se kuuluu Scale- ja Agency-pakettiin, ja paketti tarkistetaan jokaisella pyynnöllä.

Luo avain

Avaa Asetukset-osiossa API-avaimet ja paina Hallitse API-avaimia. Anna avaimelle nimi ja paina Luo avain. Avain näytetään vain kerran, joten kopioi se heti. Tallennamme siitä vain tunnisteen, emmekä voi näyttää sitä uudelleen. Jos avain katoaa, peruuta se ja luo uusi.

Lähetä avain Bearer-tunnisteena. Avain lukee vain oman tilisi sivustoja. Toisen tilin sivusto näyttää sivustolta, jota ei ole olemassa.

curl -H "Authorization: Bearer $ACCESSIBOSS_API_KEY" \
  "https://oma.lanetti.fi/api/accessiboss/v1/sites/SITE_ID/issues?state=open&severity=critical"

Pyyntö	Mitä saat
`GET /api/accessiboss/v1/sites`	Tilisi sivustot, jotka rajapinta kattaa: tunnus, verkkotunnus, paketti ja onko verkkotunnus vahvistettu.
`GET /api/accessiboss/v1/sites/{id}/status`	Paketti, vahvistus, avoimien ongelmien määrät lajeittain, viimeisin tarkistus ja linkki paneeliin.
`GET /api/accessiboss/v1/sites/{id}/scans?limit=20`	Viimeisimmät tarkistukset uusimmasta alkaen, tila ja yhteenveto. Rajana voi olla enintään 100.
`GET /api/accessiboss/v1/sites/{id}/issues`	Automaattisten tarkistusten löytämät ongelmat. Valinnaiset suodattimet: `state` (open, fixed, dismissed), `kind` (failure, bad_practice, needs_review), `severity`, `page` (tarkka sivun osoite), `limit` (enintään 200) ja `offset`.

Jokainen vastaus on JSON, jossa on "ok": true. Virheessä on "ok": false ja lyhyt error-koodi:

Tila	Koodi	Merkitys
401	`invalid_key`	Avain puuttuu, on väärä, vanhentunut tai peruutettu.
403	`plan_required`	Pakettisi ei sisällä rajapintaa.
404	`not_found`	Tililläsi ei ole tällaista sivustoa.
429	`rate_limited`	Yli 60 pyyntöä minuutissa tälle avaimelle. `Retry-After`-otsake kertoo, montako sekuntia odotetaan.

Jokaisessa vastauksessa on X-RateLimit-Limit, X-RateLimit-Remaining ja X-RateLimit-Reset. Avaimet vanhenevat 90 päivässä. Peruuta avain samassa ikkunassa, niin se lakkaa toimimasta heti. Luonti, peruutus ja jokainen luku kirjataan auditointilokiin.

Ongelmien tekstit tulevat sivustosi sisällöstä, joten käsittele niitä epäluotettavana tietona. Älä aja niitä koodina, ja neutraloi ne ennen kuin avaat ne taulukkolaskennassa.

Content-Security-Policy

script-src https://oma.lanetti.fi
connect-src https://oma.lanetti.fi
font-src https://oma.lanetti.fi
img-src data:

Jos Trusted Types on käytössä, salli käytännön nimi accessiboss. Se hyväksyy vain /embed/-polkumme alla olevat skriptiosoitteet.

Vastaat itse sivustostasi

Paneeli muuttaa vain sitä, miten sivu näytetään asetuksen valinneelle kävijälle. Se ei koskaan kirjoita uudelleen sivusi merkintöjä, ARIA-määritteitä, vaihtoehtoisia tekstejä, otsikoita tai sarkainjärjestystä. Sivuston omistaja vastaa itse sivustosta.

Oliko tämä artikkeli hyödyllinen?