# Ohjaa keskusteluikkunaa JavaScriptillä

URL: https://aihio.ai/ohjekeskus/tekoalyagentti/widget-api\
Kuvaus: Avaa keskusteluikkuna omasta painikkeesta, kuuntele tapahtumia ja välitä analytiikkasuostumus verkkosivultasi.

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](/ohjekeskus/tekoalyagentti/viestirajapinta) kutsut agenttia palvelimeltasi, [webhookilla](/ohjekeskus/tekoalyagentti/webhookit) vastaanotat tapahtumia ja [identiteettivarmistuksella](/ohjekeskus/tekoalyagentti/identiteettivarmistus) välität allekirjoitetun käyttäjätiedon.

## Ennen aloittamista

Asenna ensin Oma Aihio -palvelun antama upotuskoodi [julkaisuohjeen mukaan](/ohjekeskus/tekoalyagentti/julkaisu). 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.

```javascript
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

| 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.

> **Varoitus — Viestin lähettäminen on oikea toiminto:**
>
> `sendMessage` lähettää viestin agentille ja käyttää palvelua tavallisen
> keskustelun tavoin. Kutsu sitä vain käyttäjän tarkoituksellisen toiminnon
> seurauksena. `resetUser` ei poista palveluun tallennettuja keskusteluja.

## Kuuntele avautumista

```javascript
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:

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

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

```javascript
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.

## Uusi keskusteluikkuna (Widget Runtime v2)

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:

| 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](/ohjekeskus/tekoalyagentti/identiteettivarmistus). Pelkkä selaimesta annettu käyttäjätunniste ei todista henkilöllisyyttä.
## Seuraavat vaiheet

- [Identiteettivarmistus](/ohjekeskus/tekoalyagentti/identiteettivarmistus) — Välitä kirjautuneen käyttäjän tiedot palvelimen allekirjoittamina ja valitse oikea varmennustapa keskusteluikkunalle.