# Julkaisu

URL: https://aihio.ai/ohjekeskus/tekoalyagentti/julkaisu\
Kuvaus: Julkaise tekoälyagentti chat-widgetinä tai sivulle upotettuna keskusteluna.

Voit julkaista tekoälyagentin kelluvana chat-widgetinä tai sivun sisältöön
sijoitettuna keskusteluna. Kopioi aina juuri tämän agentin koodi Muokkaimen
**Asenna**-valikosta. Koodi sisältää oikean julkisen tunnisteen, joten sitä ei
tarvitse muokata käsin.

| Upotustapa                      | Valitse tämä, kun                                     | Huomio                                                                                      |
| ------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| **Verkkosivun chat-widget**     | Haluat kelluvan avauspainikkeen koko sivustolle       | Tukee Widget API -komentoja, analytiikkasuostumusta ja kirjautuneen käyttäjän tunnistamista |
| **Sivulle upotettu keskustelu** | Haluat keskusteluikkunan kiinteäksi osaksi yhtä sivua | Ei näytä kelluvaa avauspainiketta eikä tue isäntäsivun Widget API -komentoja                |
| **WordPress**                   | Sivustosi käyttää WordPressiä                         | Virallinen lisäosa asentaa widgetin ilman koodin kopiointia                                 |

## Ennen asennusta

1. Testaa tavallisimmat asiakaskysymykset Muokkaimen esikatselussa.
2. Tallenna muutokset ja julkaise agentti. Luonnos tai tauolla oleva agentti ei vastaa sivustolla.
3. Avaa **Asetukset → Suojaus**. Jos domain-rajoitus on käytössä, lisää jokainen käytettävä origin erikseen, esimerkiksi `https://example.com` ja `https://www.example.com`. `*.example.com` ei kata apex-domainia `example.com`.

## Asenna kelluva chat-widget

1. Avaa agentin **Muokkain**.
2. Valitse **Asenna → Verkkosivun chat-widget**.
3. Kopioi koko `<script>`-koodinpätkä.
4. Lisää koodi kerran sivuston yhteiseen pohjaan juuri ennen sulkevaa `</body>`-tagia.
5. Julkaise sivuston muutos.

Useimmat julkaisujärjestelmät tarjoavat sivustonlaajuisen Footer- tai Custom
Code -kentän. WordPressissä voit käyttää myös [virallista Aihio Chatbot
-lisäosaa](/ohjekeskus/tekoalyagentti/wordpress-lisaosa).

Jätä koodi pois kassasivuilta, joille on upotettu maksulomake. Näin
maksusivulla ajetaan vain maksamiseen tarvittavat skriptit.

### Astro-sivusto

Luo esimerkiksi `src/components/AihioWidget.astro` ja liitä Muokkaimesta
kopioitu koodi siihen. Muuta vain avaava `<script>`-tagi muotoon
`<script is:inline>`, jotta Astro ei niputa tai siirrä julkista
bootstrap-koodia.

Tuo komponentti yhteiseen layoutiin ja renderöi se kerran ennen
`</body>`-tagia:

```astro
---
import AihioWidget from '../components/AihioWidget.astro';
---

<html lang="fi">
  <body>
    <slot />
    <AihioWidget />
  </body>
</html>
```

Älä lisää chatbotin salaisuutta Astro-komponenttiin tai mihinkään
`PUBLIC_`-ympäristömuuttujaan. Upotuskoodin `chatbotId` on julkinen tunniste;
identiteettivarmistuksen salaisuus kuuluu vain palvelimelle.

## Välitä analytiikkasuostumus

Chat toimii ilman analytiikkasuostumusta. Välitä käyttäytymisanalytiikan lupa
widgetille vasta, kun kävijä on hyväksynyt sen evästehallinnassa:

```javascript
AihioWidget('consent', {
  analytics: hasAnalyticsConsent,
});
```

Korvaa `hasAnalyticsConsent` oman evästehallintasi totuusarvolla ja kutsu
komentoa aina valinnan muuttuessa. Tuntematon tai hylätty valinta tarkoittaa
arvoa `false`. Selaimen Do Not Track -asetus estää widgetin analytiikan myös
silloin, kun isäntäsivu välittää arvon `true`.

## Tunnista kirjautunut käyttäjä

Käytä tunnistamiseen lyhytikäistä, palvelimella `HS256`-allekirjoitettua JWT:tä
ja välitä selaimelle vain valmis token:

```javascript
AihioWidget('identify', {
  token: serverSignedIdentityToken,
});
```

Kutsu uloskirjautumisen yhteydessä `AihioWidget('resetUser')`, jotta seuraava
saman laitteen käyttäjä ei näe edellisen käyttäjän keskusteluhistoriaa. Katso
palvelin-esimerkit, tokenin väitteet ja turvallinen käyttöönottojärjestys
[identiteettivarmistuksen ohjeesta](/ohjekeskus/tekoalyagentti/identiteettivarmistus).
Älä koskaan allekirjoita tokenia selaimessa tai paljasta salaisuutta
upotuskoodissa.

## Upota keskustelu sivun sisältöön

1. Valitse **Asenna → Sivulle upotettu keskustelu**.
2. Kopioi koko `<iframe>`-elementti.
3. Lisää se kohtaan, jossa haluat keskustelun näkyvän.
4. Säädä ympäröivän alueen korkeus. Oletuskoodi käyttää vähintään 600 pikselin korkeutta.

Iframe sopii esimerkiksi yhteydenotto- tai tukisivulle. Valitse
skriptiupotus, jos tarvitset kelluvan avauspainikkeen, `identify`-komennon,
analytiikkasuostumuksen tai muut Widget API -komennot.

## CSP-asetukset

Jos sivustosi käyttää sisällön suojauskäytäntöä (Content Security Policy,
CSP), selain lataa vain käytännössä sallitut lähteet. Chat-widget toimii
sivusi omassa dokumentissa, joten salli nämä lähteet. Jos asennuskoodisi
lataa `aihio-loader.js`-tiedoston osoitteesta `https://aihio.ai/widget/`,
kopioi ensin uusi koodi **Asenna**-valikosta.

| Direktiivi    | Lisää                                                               | Käyttötarkoitus                                      |
| ------------- | ------------------------------------------------------------------- | ---------------------------------------------------- |
| `script-src`  | `https://app.aihio.ai` tai sivun nonce                              | Asennuskoodi, `aihio-loader.js` ja `aihio-widget.js` |
| `connect-src` | `https://app.aihio.ai`                                              | Asetukset, viestit ja vastausten suoratoisto         |
| `img-src`     | `https://negsyvjjuqqjhlsxuyzc.supabase.co` ja `https://db.aihio.ai` | Aihioon lataamasi logo ja avatar                     |
| `media-src`   | `https://app.aihio.ai`                                              | Uuden viestin ilmoitusääni                           |
| `style-src`   | `'unsafe-inline'`                                                   | Widgetin komponenttien tyylit                        |
| `frame-src`   | `https://app.aihio.ai`                                              | Vain sivulle upotettu keskustelu                     |

Inline-asennuskoodi tarvitsee lisäksi noncen tai hashin. Kun lisäät sivun
noncen asennuskoodin `<script>`-elementtiin, koodi välittää sen
`aihio-loader.js`-skriptille, joka välittää sen edelleen widgetille. Silloin
`script-src` voi sallia skriptit pelkällä noncella, myös
`'strict-dynamic'`-lähteen kanssa.
Älä lisää `script-src`-direktiiviin `'unsafe-inline'`-lähdettä widgetin takia.

`style-src` tarvitsee toistaiseksi `'unsafe-inline'`-lähteen, koska widget
lisää komponenttiensa tyylit `<style>`-elementteinä ilman noncea. Pelkkä nonce
ei vielä riitä tyylien lähteeksi. Jos samassa direktiivissä on nonce tai hash,
selain jättää `'unsafe-inline'`-lähteen huomiotta, joten poista ne tyylien
lähteistä tai käytä sivulle upotettua keskustelua.

### Trusted Types

Jos sivusi CSP:ssä on `trusted-types`- tai
`require-trusted-types-for`-direktiivi, tee nämä muutokset:

1. Jos CSP:ssä on `trusted-types`-direktiivi, lisää siihen nimi
   `svelte-trusted-html`. Widget luo tämännimisen käytännön, eikä nimi muutu.
   Jos sivustosi käyttää itse Svelte 5:tä, lisää samaan direktiiviin myös
   `'allow-duplicates'`, koska sama nimi on silloin jo käytössä.
2. Jos sivusi vaatii Trusted Types -käytäntöä
   (`require-trusted-types-for 'script'`), salli widgetin kaksi osoitetta sivun
   oletuskäytännössä ja lisää `default` myös `trusted-types`-direktiiviin, jos
   sellainen on. Asennuskoodi ja `aihio-loader.js` asettavat skriptin osoitteen
   tavallisena merkkijonona, ja Trusted Types -sivulla se onnistuu vain
   oletuskäytännön kautta.

```javascript
trustedTypes.createPolicy('default', {
  createScriptURL(url) {
    const allowed = [
      'https://app.aihio.ai/widget/aihio-loader.js',
      'https://app.aihio.ai/widget/aihio-widget.js',
    ];
    if (allowed.includes(url)) return url;
    throw new TypeError('Script URL not allowed');
  },
});
```

Jos sivullasi on jo oletuskäytäntö, lisää nämä kaksi osoitetta siihen. Selaimen
konsolin virheilmoitus kertoo, mikä puuttuu:

| Virheilmoitus                                           | Korjaus                                                        |
| ------------------------------------------------------- | -------------------------------------------------------------- |
| `Policy "svelte-trusted-html" disallowed`               | Lisää nimi `svelte-trusted-html` `trusted-types`-direktiiviin. |
| `Policy with name "svelte-trusted-html" already exists` | Lisää `'allow-duplicates'`.                                    |
| `This document requires 'TrustedScriptURL' assignment`  | Lisää oletuskäytäntö.                                          |

Jos et voi muuttaa sivun Trusted Types -käytäntöä, käytä
[sivulle upotettua keskustelua](#upota-keskustelu-sivun-sisältöön). Se
tarvitsee vain `frame-src https://app.aihio.ai` -lähteen, koska keskustelu
toimii omassa dokumentissaan.

## Valmistele saavutettavuusauditointi

Chat-widget toimii suljetussa Shadow DOM -puussa, joten saavutettavuuden
tarkistustyökalut eivät näe sen sisältöä. Avaa puu auditoinnin ajaksi
lisäämällä upotuskoodin `init`-kutsuun asetus `isolation: 'open'`.
Vanhemmassa, `<script>`-tagin data-attribuutteja käyttävässä upotuksessa lisää
tagiin attribuutti `data-isolation="open"`.

Palauta alkuperäinen koodi auditoinnin jälkeen. Avoimessa tilassa isäntäsivun
istuntojen tallennus- ja analytiikkaskriptit voivat lukea keskustelun tekstin.

## Varmista asennus

1. Avaa julkaistu sivu yksityisessä selainikkunassa.
2. Varmista, että chat-widget tai upotettu keskustelu näkyy ja vastaa testiviestiin.
3. Testaa sekä mobiili- että työpöytäleveys.
4. Testaa analytiikkasuostumuksen hyväksytty ja hylätty tila, jos välität suostumuksen.
5. Jos tunnistat käyttäjiä, tarkista **Asetukset → Suojaus** -näkymästä, että Aihio on vastaanottanut validin tokenin ennen varmistuksen pakottamista.

## Jos keskustelu ei näy

- **Selain näyttää domain-virheen:** lisää osoiterivin tarkka origin sallittuihin domaineihin. Lisää esikatselu- ja tuotantodomain erikseen.
- **Selainkonsolissa näkyy CSP-virhe:** tarkista sallitut lähteet [CSP-asetuksista](#csp-asetukset).
- **Latauspyyntö epäonnistuu:** tarkista selaimen Network-välilehdeltä, että `aihio-loader.js` ja chatbotin asetusten pyyntö palauttavat onnistuneen vastauksen.
- **Koodi näkyy vain osalla sivuista:** siirrä skripti sivuston yhteiseen layoutiin ja varmista, että se lisätään vain kerran.
- **Iframe on liian matala:** määritä ympäröivälle elementille korkeus tai muuta iframe-elementin `min-height`-arvoa.

Voit perua asennuksen poistamalla lisäämäsi `<script>`- tai `<iframe>`-elementin
ja julkaisemalla sivuston uudelleen.

## Keskeytä käyttö tai aktivoi uudelleen

Avaa agentin yläpalkin käyttötilan valikko ja valitse **Keskeytä**, kun haluat lopettaa vastaamisen tilapäisesti. Tarkista, että tila muuttuu muotoon **Keskeytetty**, ja testaa vaikutus sivustolla.

Kun haluat jatkaa käyttöä, valitse **Aktivoi** ja varmista testiviestillä, että agentti vastaa jälleen. Jos käyttöönotto estyy, tarkista valmis tietolähde ja näkyvä virheilmoitus.

Keskeyttäminen ei poista sivuston asennuskoodia. Poista koodi erikseen, jos et halua keskusteluikkunan latautuvan lainkaan. Käyttötilan muuttaminen ei myöskään palauta vanhoja ohjeita tai aiempaa asetuskokonaisuutta.
