Ohjaa keskusteluikkunaa JavaScriptillä

Avaa keskusteluikkuna omasta painikkeesta, kuuntele tapahtumia ja välitä analytiikkasuostumus verkkosivultasi.

Avaa kopiointivalikko

JavaScript-rajapinnalla voit liittää Aihion keskusteluikkunan verkkosivusi omiin toimintoihin. Tässä ohjeessa avaat ikkunan, seuraat sen avautumista ja yhdistät analytiikan sivustosi suostumusvalintaan.

Valitse integraatiotapa tehtävän mukaan: tämä ohje koskee verkkosivun keskusteluikkunaa. Viestirajapinnalla kutsut agenttia palvelimeltasi, webhookilla vastaanotat tapahtumia ja identiteettivarmistuksella välität allekirjoitetun käyttäjätiedon.

Ennen aloittamista

Asenna ensin Oma Aihio -palvelun antama upotuskoodi julkaisuohjeen mukaan . Lisää omat kutsut upotuskoodin jälkeen. Upotuskoodin komentojono ottaa kutsut vastaan myös ennen keskusteluikkunan latautumista.

Ohje koskee JavaScript-upotusta. Erillisen iframe-upotuksen sisäistä keskusteluikkunaa ei ohjata näillä isäntäsivun kutsuilla. Älä lisää samaa upotusta sivulle kahdesti.

Avaa ikkuna omasta painikkeesta

Lisää sivustollesi painike, jonka tunniste on avaa-keskustelu, ja seuraava JavaScript sivustosi omaan koodiin. Koodi olettaa, että painike ja Aihion upotuskoodi ovat jo sivulla.

document.getElementById('avaa-keskustelu')?.addEventListener('click', () => {
  window.AihioWidget('open');
});

Paina painiketta: keskusteluikkunan pitäisi avautua ilman uuden sivun lataamista. Sulje ikkuna sen omasta sulkemispainikkeesta. Poista oma tapahtumankäsittelijä, jos haluat palata pelkkään Aihion avauspainikkeeseen.

Valitse oikea komento

Valitse oikea komento
Komento	Vaikutus
`open`	Avaa keskusteluikkunan.
`close`	Sulkee keskusteluikkunan.
`show`	Näyttää avauspainikkeen.
`hide`	Piilottaa avauspainikkeen.
`toggle`	Vaihtaa avauspainikkeen näkyvyyttä, ei keskusteluikkunan aukioloa.
`sendMessage`	Lähettää annetun tekstin käyttäjän viestinä.
`identify`	Välittää käyttäjän tunnistetiedot tai palvelimen allekirjoittaman JWT:n.
`resetUser`	Tyhjentää keskusteluikkunaan asetetun käyttäjän identiteetin esimerkiksi uloskirjautumisen yhteydessä.
`consent`	Päivittää analytiikkasuostumuksen.
`on`	Rekisteröi tapahtumankäsittelijän.

init kuuluu Oma Aihio -palvelun tuottamaan upotuskoodiin. Älä alusta ikkunaa uudelleen sen avaamiseksi. update on olemassa ajonaikaisia asetuksia varten, mutta tavalliset ulkoasumuutokset kannattaa tehdä Oma Aihio -palvelussa.

Kuuntele avautumista

window.AihioWidget('on', 'open', () => {
  console.info('Keskusteluikkuna avautui');
});

Avaa ikkuna ja tarkista selaimen konsolista ilmoitus. Rekisteröi käsittelijä kerran, jotta esimerkiksi sivustosi reittivaihto ei lisää sitä toistuvasti.

Tuetut tapahtumat ovat ready, open, close, message ja error. message sisältää viestin roolin, sisällön ja tunnisteen. Älä tallenna keskustelujen sisältöä analytiikkaan tai konsoliin. Tavalliseen avautumisen seurantaan riittää open ilman viestitietoja.

Yhdistä analytiikkasuostumus

Välitä sivustosi suostumuksenhallinnan todellinen valinta. Kutsu seuraavaa vain, kun käyttäjä on hyväksynyt analytiikan:

window.AihioWidget('consent', { analytics: true });

Kun käyttäjä kieltää analytiikan tai peruu aiemman suostumuksen, välitä kielto:

window.AihioWidget('consent', { analytics: false });

Puuttuva suostumus ei salli käyttäytymisanalytiikkaa. Selaimen Do Not Track -valinta estää sen myös annetun suostumuksen jälkeen. Suostumuskutsu ei korvaa sivustosi suostumuksenhallintaa eikä koske kaikkia keskustelun toimittamiseen tarvittavia pyyntöjä.

Testaa hyväksyminen ja peruminen erikseen selaimen verkkopyyntönäkymässä. Kielletystä analytiikasta ei saa lähteä käyttäytymisen seurantatapahtumia; keskustelun omat palvelupyynnöt voivat edelleen toimia. Älä päättele suostumuksen toteutumista pelkästään ikkunan avautumisesta.

Kun Oma Aihio antaa upotuskoodin, jonka skriptiosoite päättyy /widget/v2/loader.js, sivullasi on uusi keskusteluikkuna. Kutsutapa on sama window.AihioWidget(...), mutta komentojoukko on suppeampi ja tarkoituksella tiukempi:

Uusi keskusteluikkuna (Widget Runtime v2)
Komento	Vaikutus
`open`, `close`	Avaa tai sulkee keskusteluikkunan.
`show`, `hide`	Näyttää tai piilottaa avauspainikkeen.
`on`, `off`	Lisää tai poistaa tapahtumakäsittelijän.
`requestConversationReset`	Kutsu `AihioWidget('requestConversationReset', { version: 1 })`. Avaa kävijälle vahvistuksen keskustelun päättämisestä; ei päätä sitä itse. Toimii vasta, kun keskustelun päättäminen on otettu käyttöön; muuten ikkuna lähettää `error`-tapahtuman.
`destroy`	Poistaa ikkunan ja painikkeen sivulta.

Tapahtumat ovat ready, open, close, message ja error. Uudessa ikkunassa message kertoo vain, että agentti vastasi: se ei sisällä viestin tekstiä, roolia tai tunnistetta, joten keskustelun sisältö pysyy ikkunan sisällä.

toggle, sendMessage, identify, resetUser, consent ja update eivät ole käytössä uudessa ikkunassa. Kirjautuneen käyttäjän tunnistus ja aloituslomake tulevat uuteen ikkunaan omina ominaisuuksinaan; siihen asti tunnistusta tai pakollista aloituslomaketta vaativat agentit käyttävät nykyistä ikkunaa. Viestin lähettäminen käyttäjän puolesta jää pois tarkoituksella.

Jos kutsu ei toimi

AihioWidget puuttuu: tarkista upotuskoodin latautuminen ja oman koodisi suoritusjärjestys.
Painike ei reagoi: tarkista HTML-elementin tunniste ja että käsittelijä lisätään vasta elementin olemassa ollessa.
toggle ei sulje ikkunaa: käytä sulkemiseen close-komentoa.
sendMessage tai identify ei tee mitään: upotuskoodisi lataa uuden ikkunan (/widget/v2/loader.js), jossa komentoja ei ole.
Suostumuksen peruminen ei välity: varmista kentän tarkka nimi analytics ja totuusarvo false, ei merkkijonoa 'false'.

Kirjautuneen käyttäjän tiedot tarvitsevat erillisen identiteettivarmistuksen . Pelkkä selaimesta annettu käyttäjätunniste ei todista henkilöllisyyttä.