# 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. `open({ draft: 'teksti' })` täyttää lisäksi tyhjän viestikentän enintään 2 000 merkin tekstillä; kävijä päättää, lähettääkö viestin.  |
| `close`     | Sulkee keskusteluikkunan.                                                                                                                                     |
| `show`      | Näyttää avauspainikkeen.                                                                                                                                      |
| `hide`      | Piilottaa avauspainikkeen.                                                                                                                                    |
| `toggle`    | Vaihtaa avauspainikkeen näkyvyyttä, ei keskusteluikkunan aukioloa.                                                                                            |
| `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.                                                                                                                            |
| `off`       | Poistaa `on`-komennolla rekisteröidyn käsittelijän. Anna sama funktio, jonka rekisteröit.                                                                     |
| `update`    | Muuttaa ajonaikaisia asetuksia. Tee tavalliset ulkoasumuutokset Oma Aihio -palvelussa.                                                                        |
| `init`      | Käynnistää keskusteluikkunan. Oma Aihio -palvelun tuottama upotuskoodi kutsuu sitä jo; älä käytä sitä ikkunan avaamiseen.                                     |
| `destroy`   | Poistaa keskusteluikkunan ja avauspainikkeen sivulta, esimerkiksi kun suostumus perutaan. Toistettu kutsu ei tee mitään. Uusi `init` käynnistää ne uudelleen. |

> **Huomaa — Kävijä lähettää viestin itse:**
>
> Mikään komento ei lähetä viestiä kävijän puolesta. `open({draft})` täyttää
> viestikentän vain, kun se on tyhjä, ja kävijä päättää, lähettääkö viestin.
> `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.

| Tapahtuma | Milloin                                                                                                                             |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `ready`   | Keskusteluikkuna on ladannut asetuksensa. Tavallisella upotuskoodilla tämä tapahtuu yleensä, kun ikkuna avataan ensimmäisen kerran. |
| `open`    | Keskusteluikkuna avautuu joko koodisi kutsusta tai avauspainikkeesta.                                                               |
| `close`   | Keskusteluikkuna sulkeutuu.                                                                                                         |
| `message` | Keskusteluun lisätään viesti. Sisältää viestin tunnisteen ja roolin, ei koskaan viestin tekstiä.                                    |
| `error`   | Keskusteluikkuna ei pystynyt lataamaan asetuksiaan.                                                                                 |

Mikään tapahtuma ei sisällä keskustelun tekstiä. Tavalliseen avautumisen seurantaan riittää `open`.

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

## Tunnista kirjautunut käyttäjä

Tunnistetiedot kulkevat pyyntöjen otsaketiedoissa, joten niissä saa olla vain Latin-1-merkkejä. Jos `name`- tai `email`-arvossa on muita merkkejä, kuten nimessä "Šárka", arvo jätetään pois ja muut tunnistetiedot säilyvät. Jos muita merkkejä on `externalId`-, `user_hash`- tai `token`-arvossa, koko tunnistus jätetään pois, ikään kuin `identify`-komentoa ei olisi kutsuttu.

Kun sivustosi tietää, kuka kävijä on, välitä tunniste ikkunalle:

```javascript
window.AihioWidget('identify', {
  externalId: 'asiakas-12345',
  name: 'Maija Meikäläinen',
  email: 'maija@example.com',
  user_hash: 'palvelimella laskettu HMAC-todiste',
});
```

Kentät ovat `externalId` (tai Chatbase-yhteensopiva `user_id`), `email`, `name`, `user_hash` ja
`token` (palvelimen allekirjoittama JWT). Anna `token`-kentän kanssa myös `getToken`-funktio,
joka palauttaa saman käyttäjän uuden JWT:n, kun vanha vanhenee. Muita kenttiä ei tarvita. `user_hash` ja `token` ovat
todiste kävijän henkilöllisyydestä, ja palvelin varmistaa sen agentin omalla avaimella; ilman
todistetta tunniste on vain vihje eikä sido keskustelua kävijään. Kutsu `resetUser`
uloskirjautumisen yhteydessä.

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