Asennusoppaat

:::note Versiotila Julkaistu npm-SDK 0.1.4 ja widget.js v15 tukevat teardownia remove()- tai window.ChattyBox.destroy()-kutsulla ja peruuttavat odottavan työn. :::

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 Test Chat -toiminnolla.

Luo sitten selainkäyttöön sopiva avain Public Keys -osiossa. Se toimii oletuksena tuotanto-, esikatselu-/staging- ja localhost-origin-osoitteissa. Jos haluat valinnaisesti vahvistaa suojausta, valitse Edit origins, ota käyttöön Restrict this key to specific origins ja lisää täsmälliset sallitut origin-osoitteet. Kun rajoitus on käytössä, täsmäytyksessä huomioidaan skeema, isäntänimi ja portti: https://example.com, https://preview.example.com ja http://localhost:3000 ovat erillisiä merkintöjä. Palaa Embed-osioon, valitse avain, viimeistele mahdolliset hostatun widgetin mukautukset 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>

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.
`data-debug="true"`	Ei	Ottaa selaindiagnostiikan käyttöön; oletuksena pois.

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 Public Keys > Edit origins, ota rajoitus käyttöön ja lisää tai poista tuotanto-, staging-, esikatselu- tai localhost-origin-osoitteita.
Haravointi, uudelleenharavointi, testichat, Analytics 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 sallitut origin-osoitteet säilyvät projektin käyttöönottotunnuksina, eivät asetustiedoston arvoina.

Asenna vain yksi loader. Widget hakee määrityksen ja käännökset kerran alustuksessa eikä seuraa hallintapaneelin asetusten tai sivun kielen muutoksia. Lataa sivu uudelleen tallennettujen asetusten hakemiseksi. Origin-rajoitukset ovat käytössä vain, jos ne on otettu erikseen käyttöön; ne eivät ole autentikointia.

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. Julkaistussa SDK:ssa 0.1.4 identtiset mountit jakavat scriptin ja viitteen; remove() on idempotentti ja vain viimeinen kahva signaloi v15-teardownin, joka poistaa UI:n, tyylit, fontit, scriptin ja globaalin API:n sekä peruu odottavan työn. Eri valinnat hylätään niin kauan kuin kahvoja on.

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 nykyisen sivun kielen perusteella tai luota sivun <html lang>-arvoon.

Pidä lataaja pysyvässä sovellusshellissä. Älä luo tai poista sitä normaalien asiakaspuolen reittimuutosten aikana. Fixed-tila käyttää projektin oletuslokaalia, ellei sallittu scriptiohitus ole läsnä; locale ratkaistaan vain alustuksessa, joten uusi sivun kieli edellyttää täyttä sivun latausta.

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.

Avaa GTM-säilösi.
Luo uusi Custom HTML -tagi.
Liitä ChattyBox-koodinpätkä.
Käytä All Pages -laukaisinta tai suppeampaa laukaisinta vain sivuille, joilla widgetin tulee näkyä.
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ä.

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: sulje kassa-, tili-, salasanasuojatut ja jäsenyyssivut erikseen. 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ä projektin Embed-välilehdeltä saatava widgetin julkinen API-avain ja ota chatbot käyttöön. Tuotannon API-päätepiste määritetään automaattisesti. Katso reittien poissulkemiset ja manuaalinen varavaihtoehto Drupal-chatbotmoduulin oppaasta.

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 origin-osoitteet vain, jos otit avaimelle erikseen käyttöön rajoituksen.

Ennen asennusta​

Mitä skriptiin kuuluu​

Tavallinen HTML​

Next.js / React-sovelluksen shell​

Docusaurus​

Mukautettu käyttöliittymä​

Yleinen CMS / mukautettu HTML​

Google Tag Manager​

WordPress-lisäosan opas​

Drupal-moduuli​

Vahvistus​

Tietosuojavalinnat