Asennusoppaat

:::note Versiotila Julkaistu npm-SDK 0.1.4 laskee identtisten mounttien viitteet. Kun viimeinen täsmäävä kahva poistetaan, hostattu widget.js v15 voi purkaa käyttöliittymänsä ja peruuttaa odottavan työn; window.ChattyBox.destroy() on käytettävissä v15:n alustamisen jälkeen. :::

Hostattu widget.js-integraatio on build-vapaa vaihtoehto, kun haluat ChattyBoxin ylläpitävän käyttöliittymää ja tiedonsiirtoa. Jos sovelluksesi pitäisi alustaa sama käyttöliittymä npm-koodista, käytä mountWidget(). Jos haluat hallita käyttöliittymää itse, käytä headless SDK:ta.

Ennen asennusta

Suorita ensin Näin pääset alkuun -vaiheet: määritä ja haravoi lähde, tarkista indeksoidut sivut ja varmista edustavat vastaukset Testaa chatbottia -toiminnolla.

Valmistele sitten asennus verkkosivustollesi tai hallitse selainkäyttöön sopivaa avainta kohdassa Asenna → Avaimet ja verkkotunnukset. Tarkista avaimen origin-asetukset: verkkosivustolle valmisteltu avain voi olla jo rajattu kyseiseen originiin, kun taas ilman rajoituksia luodut avaimet toimivat eri origineissa. Kohdassa Muokkaa origin-osoitteita voit ottaa käyttöön valinnaisia rajoituksia tai lisätä tarvitsemasi tuotanto-, esikatselu-, staging- ja localhost-origin-osoitteet. Kun rajoitus on käytössä, täsmäytyksessä huomioidaan tarkasti skeema, isäntänimi ja portti: https://example.com, https://preview.example.com ja http://localhost:3000 ovat erillisiä merkintöjä. Valitse avain kohdassa Verkkosivuston asennus ja kopioi luotu koodinpätkä. Se sisältää projektisi julkisen avaimen ja API-URL-osoitteen:

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-api-url="YOUR_WIDGET_API_URL"
  async
></script>

Syötä ensin HTTP(S)-verkkosivusto-URL kohdassa Asenna → Verkkosivuston asennus. Valitsin näyttää vain vanhentumattomat avaimet, joilla ei ole rajoituksia tai jotka ovat sallittuja URL:n originille. Valitse rajoitettu avain syöttämällä sallittu origin; tarkista rajoitukset kohdasta Hallinnoi avaimia ja sallittuja verkkotunnuksia. Jos lomake ei ole käytettävissä, suorita ensin hallintapaneelissa näytetty asennusvaihe.

Dokumentaatiopohjaisille alustoille löydät ohjeet seuraavista: MkDocs AI-chatbot, VitePress AI-chatbot ja GitBook AI-chatbot.

Korvaa YOUR_API_KEY hallintapaneelisi julkisella widget-avaimella. Säilytä data-api-url-arvo täsmälleen hallintapaneelissa näkyvässä muodossa. Tuotannossa tämä on julkisen widget-API:n vakaa https://...convex.site/chat-URL.

Mitä skriptiin kuuluu

Käytä skriptiattribuutteja arvoille, joiden on oltava saatavilla ennen widgetin käynnistymistä:

Attribuutti	Pakollinen	Käyttö
src	Kyllä	ChattyBox-widgetin JavaScriptin lataaminen.
data-api-key	Kyllä	Projektisi julkisen widget-avaimen tunnistaminen.
data-api-url	Kyllä	Widget-pyyntöjen lähettäminen ChattyBox API:lle.
data-locale	Ei	Pyytää käyttöliittymän kieltä alustuksessa vain, kun projekti sallii skriptiohitukset.
data-chattybox-widget="true"	Ei	Auttaa dynaamisia lataajia ja SDK:ta löytämään olemassa olevan scriptin; suositellaan, kun skripti lisätään sovelluskoodista.
data-debug="true"	Ei	Ottaa selaindiagnostiikan käyttöön; oletuksena pois.
data-color	Ei	Nimenomainen korostusvärin ohitus onnistuneen asetushaun jälkeen; käytä kuusinumeroista heksadesimaaliarvoa. Suosi hallintapaneelin asetusta.
data-position	Ei	Nimenomainen sijainnin ohitus onnistuneen asetushaun jälkeen: bottom-right, bottom-left, top-right tai top-left. Suosi hallintapaneelin asetusta.

Käytä hallintapaneelin asetuksia kaikkeen, mitä pitäisi hallita ilman sivuston uudelleenjulkaisua:

• Widgetin värit, sijainti, kuvake, otsikko ja tervetuloviesti.
• Oletuskielitila ja se, sallitaanko data-locale-ohitukset.
• Julkisten avainten luonti ja poistaminen sekä valinnaiset avainkohtaiset origin-rajoitukset. Avaa Asenna → Avaimet ja verkkotunnukset ja Muokkaa origin-osoitteita, ota rajoitus käyttöön ja lisää tai poista tuotanto-, staging-, esikatselu- tai localhost-origin-osoitteita.
• Haravointi, uudelleenharavointi, testichat, Analytiikka ja sisältöaukot.

Jos otat asetukset koodina -lukituksen käyttöön, avustaja, lähde, runtime ja tuetut widget-asetukset tulevat käyttöön otetusta konfiguraatiosta hallintapaneelin lomakkeiden sijaan. Julkiset avaimet ja valinnaiset origin-rajoitukset säilyvät projektin asennusasetuksina, eivät asetustiedoston arvoina.

Asenna vain yksi loader. SDK tunnistaa yllä olevan tunnisteattribuutin, ei jokaista manuaalista skriptiä, jolla on sama src. Julkaistu SDK 0.1.4 laskee viitteet vain identtisille mount-asetuksille ja hylkää muuttuneen avaimen, endpointin, skriptin URL:n, localen tai debug-asetuksen, kunnes kaikki kahvat on poistettu. Widget ei tilaa hallintapaneelin määritysmuutoksia; alusta se uudelleen tallennettujen asetusten hakemiseksi. Nykyisessä lähdekoodissa hostatun widget.js v16:n <html lang>- tai loaderin data-locale-muutos voi päivittää widgetin tekstit, kun ratkaistu locale muuttuu, projektin kielikäytännön rajoissa. Varmista käytössä olevan loaderin versio ennen kuin luotat reaaliaikaisiin päivityksiin; tämä toiminta on erillinen julkaistusta npm-SDK-versiosta. Kun origin-rajoitukset on otettu käyttöön, tarkistus käyttää Origin-otsaketta tai Referer-otsakkeen fallback-originia; puuttuva tai kielletty origin palauttaa 401 Invalid API key. Rajoitukset eivät ole tunnistautumista.

API-URL-osoite voi olla HTTP-palvelun juuriosoite tai päättyä /chat-polkuun; loader poistaa lopun vinoviivat ja lopussa olevan /chat-päätteen ennen päätepisteiden muodostamista. Se ei muunna Convexin .cloud-URL-osoitteita .site-muotoon. Älä sisällytä arvoon kyselymerkkijonoa tai fragmenttia.

Tavallinen HTML

Liitä koodinpätkä kerran lähelle body-elementin loppua, juuri ennen </body>-tagia. Tämä toimii staattisessa HTML:ssä, käsin koodatuilla sivustoilla ja malleissa, joissa on yhteinen alatunniste.

<!doctype html>
<html lang="en">
  <head>
    <title>Example Site</title>
  </head>
  <body>
    <main>
      <!-- Page content -->
    </main>

    <script
      src="https://chattybox.ai/widget.js"
      data-api-key="YOUR_API_KEY"
      data-api-url="YOUR_WIDGET_API_URL"
      async
    ></script>
  </body>
</html>

Next.js / React-sovelluksen shell

Lisää Next.js App Router -sivustolla widget app/layout.tsx-tiedostoon next/script-komponentilla, jotta se latautuu kerran koko sovellukseen.

import Script from "next/script";
import type { ReactNode } from "react";

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://chattybox.ai/widget.js"
          data-api-key="YOUR_API_KEY"
          data-api-url="YOUR_WIDGET_API_URL"
          data-chattybox-widget="true"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

Lisää Reactin yhden sivun sovelluksessa skripti kerran ylimmän tason sovellusshelliin tai HTML-malliin. Älä lisää sitä jokaisesta reittikomponentista. Pidä lataaja pysyvässä shellissä normaalin navigoinnin aikana. Reittikohtaista poistoa tai suostumuksen peruuttamista varten poista kaikki SDK 0.1.4 -kahvat: viimeinen täsmäävä kahva käynnistää hostatun widget.js v15:n teardownin, joka poistaa sen käyttöliittymän ja tyylit sekä peruu odottavan alustuksen, uudelleenyritykset (enintään 10 yritystä 30 sekunnissa) ja käynnissä olevan chatin. window.ChattyBox.destroy() on käytettävissä v15:n alustamisen jälkeen. Teardown ei voi perua palvelimen jo käsittelemää pyyntöä. Widget kelluu document.body-elementin alla, ei sitä lataavan komponentin sisällä.

import { useEffect } from "react";

export function ChattyBoxWidget() {
  useEffect(() => {
    if (document.getElementById("chattybox-widget-script")) return;

    const script = document.createElement("script");
    script.id = "chattybox-widget-script";
    script.src = "https://chattybox.ai/widget.js";
    script.async = true;
    script.setAttribute("data-api-key", "YOUR_API_KEY");
    script.setAttribute("data-api-url", "YOUR_WIDGET_API_URL");
    script.setAttribute("data-chattybox-widget", "true");
    document.body.appendChild(script);
  }, []);

  return null;
}

Docusaurus

Luo tai päivitä Docusaurusissa src/theme/Root.tsx, jotta widget on käytettävissä kaikilla dokumentaatiosivuilla.

import React, { useEffect } from "react";

export default function Root({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    if (document.getElementById("chattybox-widget-script")) return;

    const script = document.createElement("script");
    script.id = "chattybox-widget-script";
    script.src = "https://chattybox.ai/widget.js";
    script.async = true;
    script.setAttribute("data-api-key", "YOUR_API_KEY");
    script.setAttribute("data-api-url", "YOUR_WIDGET_API_URL");
    script.setAttribute("data-chattybox-widget", "true");
    document.body.appendChild(script);
  }, []);

  return <>{children}</>;
}

Jos Docusaurus-sivustollasi on käännetyt reitit, määritä data-locale ennen latausta, kun ohitukset ovat sallittuja, tai käytä automaattista tilaa ja sivun <html lang>-arvoa. Kiinteä-tila käyttää projektin oletuslocalea, ellei sallittua skriptin ohitusta ole.

Pidä lataaja pysyvässä sovellusshellissä. Älä luo sitä uudelleen normaalien asiakaspuolen reittimuutosten aikana; käytä tarkoitukselliseen purkamiseen hostatun widgetin tuhoamis-API:a tai poista kaikki SDK:n mount-kahvat, jos käytit SDK:ta. Nykyisessä lähdekoodissa hostatun widget.js v16:n data-locale- tai <html lang>-muutos voi päivittää käyttöliittymän tekstit, kun ratkaistu locale vaihtuu; varmista käytössä olevan loaderin versio ennen kuin luotat toimintaan. Itse kirjoitettua otsikkoa ja tervetuloviestiä tai luotuja vastauksia ei käännetä automaattisesti.

Mukautettu käyttöliittymä

Hostattu widget on valinnainen. Jos haluat täyden hallinnan renderöintiin, viestien tilaan ja vuorovaikutussuunnitteluun, käytä JavaScript SDK:ta samalla julkisella widget-API-avaimella ja widget-API-URL:lla.

Yleinen CMS / mukautettu HTML

Useimmilla CMS-alustoilla on globaali mukautetun koodin, alatunnisteen tai teeman mallin alue. Lisää skripti sinne, jotta widget latautuu jokaiselle julkiselle sivulle.

Käytä tätä tapaa Webflow-, Framer-, Squarespace- ja Wixin mukautetun koodin alueilla, Shopify-teemoissa, HubSpot-malleissa ja mukautetuissa CMS-alustoissa, joissa globaalia HTML:ää voi muokata.

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-api-url="YOUR_WIDGET_API_URL"
  async
></script>

Varmista ennen julkaisua, ettei CMS poista data-api-key-, data-api-url- tai async-attribuuttia mukautetuista skripteistä.

Google Tag Manager

Käytä Google Tag Manageria, jos tiimisi hallitsee kolmannen osapuolen skriptejä jo GTM:n kautta.

1. Avaa GTM-säilösi.
2. Luo uusi Custom HTML -tagi.
3. Liitä ChattyBox-koodinpätkä.
4. Käytä All Pages -laukaisinta tai suppeampaa laukaisinta vain sivuille, joilla widgetin tulee näkyä.
5. Esikatsele säilö, varmista widgetin latautuminen ja julkaise sitten.

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-api-url="YOUR_WIDGET_API_URL"
  async
></script>

Jos sivustosi käyttää suostumustilaa tai tagien suostumuskäytäntöä, varmista, että widget saa latautua sivuilla, joilla kävijät tarvitsevat apua. Kapeampi SPA-laukaisin estää alkulatauksen poissuljetulla reitillä, mutta ei poista widgetiä, joka on jo ladattu toisella reitillä. Älä laukaise lataajaa toistuvasti selainhistorian muutoksissa.

Content Security Policy

Salli oletusarvoiselle hostatulle loaderille https://chattybox.ai direktiivissä script-src ja widgetin API-origin direktiivissä connect-src. Widget lisää tyylitiedoston ja inline-tyylimääritteitä; sillä ei tällä hetkellä ole nonce-vaihtoehtoa, joten inline-tyylit kieltävä käytäntö estää osan käyttöliittymästä. Jos käytäntö sallii sen, salli näille tyyleille 'unsafe-inline' tai käytä käytäntöön sopivaa omaa käyttöliittymää. Inter-fontin lataaminen käynnistyskuvaketta käytettäessä edellyttää myös osoitetta https://fonts.googleapis.com direktiivissä style-src ja osoitetta https://fonts.gstatic.com direktiivissä font-src. Salli määritetyn kuvakkeen kuvapalvelimen origin direktiivissä img-src. Tarkista suostumus- ja tietoturvavaatimukset ennen CSP:n lieventämistä.

WordPress-lisäosan opas

Koodittomaan WordPress-asennukseen käytä ChattyBoxin WordPress-lisäosaa. Seuraa WordPress-lisäosan opasta asentaaksesi, määrittääksesi, sulkeaksesi reittejä pois ja vahvistaaksesi sen. Tuotannon API-päätepiste määritetään automaattisesti.

Lisäosa jaellaan julkisesta GitHub-repositoriosta kiinnitettynä ZIP-pakettina, ei WordPress.org Plugin Directorysta. Lataa version 0.2.0 kiinnitetty ZIP, avaa WordPressissä Plugins > Add New > Upload Plugin, lataa ZIP ja aktivoi ChattyBox AI Chatbot. Älä etsi lisäosaa WordPress.orgin hakemistosta.

Lisäosa lataa hostatun widgetin julkisissa frontend-pyynnöissä muokkaamatta teemaa. Se ei lataa widgetiä tarkoituksella wp-adminissa, syötteissä eikä REST- tai AJAX-pyynnöissä. Tämä ei ole kaikkien frontend-sivujen yksityisyys- tai käyttöoikeustarkistus. Tarvittaessa toteuta ja testaa kassa-, tili-, salasanasuojattujen tai jäsenyyssivujen poissulkeminen lisäosan suodattimella tai käytä sopivasti rajattua manuaalista asennusta. Lisäosan loader-URL:n muuttaminen ei muuta sen sisäänrakennettua tuotannon API-päätepistettä; käytä manuaalista katkelmaa toiselle API-käyttöönotolle.

Jos haluat asentaa skriptin manuaalisesti, käytä jotakin WordPress-asennuksesi jo tukemaa skriptisijaintia:

• Teema-asetukset, joissa voi lisätä ylä- tai alatunnisteskriptejä.
• Lapsiteema, joka hallitsee alatunnistemallia.
• Ylä-/alatunnisteskriptien lisäosa.
• Google Tag Manager, jos WordPress-sivustosi käyttää sitä jo.

Liitä koodinpätkä yhteiseen alatunnistesijaintiin, jotta se näkyy julkaistuilla sivuilla, viesteissä, dokumentaatiossa ja tietopohja-artikkeleissa, joilla chatbotin pitää olla käytettävissä.

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-api-url="YOUR_WIDGET_API_URL"
  async
></script>

Vältä widgetin lisäämistä wp-admin-, kassa-, tili- tai yksityisen jäsenyyden sivuille, elleivät sivut ole tarkoituksella julkisia ja tuettuja.

Drupal-moduuli

Drupal 10- tai 11 -sivustolla Composer on suositeltu asennustapa. Moduuli ei ole vielä Drupal.orgissa tai Packagistissa, joten lisää julkinen GitHub VCS -repositorio sitä käyttävän Drupal-projektin juuren composer.json-tiedostoon:

{
  "repositories": {
    "chattybox-drupal": {
      "type": "vcs",
      "url": "https://github.com/OpenStaticFish/chattybox-drupal.git"
    }
  }
}

Asenna sitten merkitty moduuli ja ota se käyttöön:

composer require openstaticfish/chattybox-drupal:^0.1
drush en chattybox

Avaa Configuration > Web services > ChattyBox, liitä widgetin julkinen API-avain Verkkosivuston asennus -osion koodinpätkästä ja ota chatbot käyttöön. Paikallisesti tarkastettu moduuliversio käyttää kovakoodattua API-päätepistettä. Vertaa sitä koodinpätkään ja käytä manuaalista integraatiota toiselle API-käyttöönotolle. Katso reittien poissulkemista, välimuistia ja suostumusta koskevat ohjeet Drupal-chatbotmoduulin oppaasta.

Moduuli on oletusarvoisesti poissa käytöstä. Se ohittaa hallinnolliset ja muut kuin HTML-pyynnöt, ei kaikkea yksityistä frontend-sisältöä. Skriptin URL:n muuttaminen ei muuta sisäänrakennettua tuotannon API-päätepistettä. Käytä moduulin sijasta manuaalista widget-koodinpätkää, jos tarvitset toisen API-käyttöönoton.

Vahvistus

Suorita asennuksen jälkeen julkaisun tarkistuslista ennen chatbotin ilmoittamista:

• Avaa julkinen sivu incognito-ikkunassa.
• Varmista, että widgetin avaaja näkyy.
• Avaa widget ja esitä todellinen asiakaskysymys.
• Varmista, että tuettu vastaus sisältää olennaiset lähdeviitteet, ja tarkista, että tukematon kysymys käyttää varavastausta; varavastauksella voi olla tyhjät lähteet.
• Tarkista selaimen konsolista puuttuva data-api-key, puuttuva data-api-url tai avain-/origin-virheet.
• Tarkista avaimen origin-asetukset ja, jos rajoitus on käytössä, testattavan originin sallinta; asennusta varten valmisteltu avain voi jo olla rajoitettu.

Lataa vain yksi loader per sivu. Widget ei seuraa hallintapaneelissa tallennettuja määritysmuutoksia; alusta se uudelleen tallennettujen asetusten hakemiseksi. Nykyisessä lähdekoodissa hostatun widget.js v16:n tuotteen omat tekstit voivat päivittyä localen vaihtuessa yllä kuvatulla tavalla, mutta varmista käytössä oleva versio ennen siihen luottamista. Itse kirjoitettua otsikkoa ja tervetuloviestiä tai luotuja vastauksia ei käännetä automaattisesti. Tarkista asennusta testatessasi avaimen origin-asetukset, myös se, onko rajoitus käytössä ja sisältyykö sallittuihin origineihin testattava origin; asennusta varten valmisteltu avain voi olla jo rajattu. Origin-rajoitukset täsmäävät skeeman, isännän ja portin mukaan tarkasti, eivätkä ole tunnistautumista.