Paigaldusjuhendid

:::note Versiooni olek Avaldatud npm-SDK 0.1.4 koos widget.js v15-ga toetab teardowni remove() või window.ChattyBox.destroy() abil ja katkestab ootel töö. :::

Hostitud widget.js-integratsioon on ehituseta tee, kui soovite, et ChattyBox haldaks kasutajaliidest ja transpordikihti. Kui teie rakendus peaks sama kasutajaliidese npm-koodist lähtestama, kasutage mountWidget(). Kui soovite kasutajaliidest ise hallata, kasutage peata SDK-d.

Enne paigaldamist

Lõpetage esmalt Alustamise töövoog: konfigureerige ja importige allikas, vaadake indekseeritud lehed üle ning kontrollige tüüpilisi vastuseid Testi vestlusrobotit vaates.

Jaotises Paigalda → Veebisaidi paigaldamine valmistage veebisaidi jaoks paigaldus ette või hallake brauseris turvalist võtit jaotises Paigalda → Võtmed ja domeenid. Kontrollige origin’i piiranguid: veebisaidi domeeni jaoks ettevalmistatud võti võib juba olla sellele origin’ile piiratud, samas kui piiranguteta loodud võtmed töötavad kõigist origin’idest. Jaotises Muuda origine saate piirangud valikuliselt sisse lülitada või lisada täpsed lubatud origin’id; skeem, hostinimi ja port peavad kõik ühtima. Jaotises Veebisaidi paigaldamine sisestage veebisaidi HTTP(S) URL. Valik näitab aegumata võtmeid, mis on piiranguteta või lubatud selle URL-i origin’i jaoks; piiratud võtme valimiseks sisestage selle lubatud origin. Valige sobiv võti ja kopeerige loodud koodilõik. Kui vorm pole saadaval, lõpetage esmalt juhtpaneelil näidatud seadistussamm. Koodilõik sisaldab teie projekti avalikku võtit ja API URL-i:

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

Dokumendikesksete platvormide puhul vaadake MkDocsi AI-vestlusroboti, VitePressi AI-vestlusroboti ja GitBooki AI-vestlusroboti juhendeid.

Asendage YOUR_API_KEY juhtpaneelilt saadud avaliku vidinavõtmega. Hoidke data-api-url väärtus täpselt sellisena, nagu juhtpaneel seda näitab. Tootmises on see avaliku vidina API stabiilne https://...convex.site/chat URL.

Mis kuulub skripti

Kasutage skriptiatribuute väärtuste jaoks, mis peavad olema kättesaadavad enne vidina käivitumist:

Atribuut	Nõutud	Kasutage seda
src	Jah	ChattyBoxi vidina JavaScripti laadimiseks.
data-api-key	Jah	Projekti avaliku vidinavõtme tuvastamiseks.
data-api-url	Jah	Vidinapäringute saatmiseks ChattyBoxi API-le.
data-locale	Ei	Kasutajaliidese keele taotlemiseks algkäivitamisel ainult siis, kui projekt lubab skripti override’e.
data-chattybox-widget="true"	Ei	Lubab dünaamilistel laadijatel ja SDK-l olemasoleva skripti leida; soovitatav, kui lisate skripti rakendusekoodist.
data-debug="true"	Ei	Lülitab sisse brauseri diagnostika; vaikimisi väljas.
data-color	Ei	Alistab pärast edukat konfiguratsioonipäringut rõhuvärvi; kasutage kuuekohalist kuueteistkümnendvärvi ja eelistage juhtpaneeli.
data-position	Ei	Alistab pärast edukat konfiguratsioonipäringut asukoha: bottom-right, bottom-left, top-right või top-left; eelistage juhtpaneeli.

Kasutage juhtpaneeli seadeid kõige jaoks, mida tuleks hallata veebisaidi uuesti juurutamata:

• Vidina värvid, asukoht, ikoon, pealkiri ja tervitussõnum jaotises Kohanda → Välimus.
• Vaikekeelerežiim ja see, kas data-locale-i ülekirjutused on lubatud.
• Avalike võtmete loomine ja kustutamine ning valikulised origin’i piirangud jaotises Paigalda → Võtmed ja domeenid. Piirangu lubamiseks ja origin’ide lisamiseks või eemaldamiseks avage Muuda origine.
• Kraapimine, uuesti kraapimine, testvestlus, Analytics ja sisulüngad.

Kui lubate konfiguratsioon koodina luku, pärinevad assistent, allikas, runtime ja toetatud vidinaseaded juurutatud konfiguratsioonist, mitte juhtpaneeli vormidest. Avalikud võtmed ja lubatud origin’id jäävad projekti seadeteks, mitte konfiguratsioonifaili väärtusteks.

API URL võib olla HTTP juurutuse juur või lõppeda /chat-iga; laadija eemaldab lõpus olevad kaldkriipsud ja lõpu /chat. See ei teisenda Convexi .cloud URL-i .site-iks. Ärge lisage päringustringi ega fragmenti. Kui origin’i piirang on lubatud, kasutab kontroll Origin-it või varuvariandina Referer-i origin’it; puuduva või keelatud origin’i korral tagastatakse 401 Invalid API key. See pole külastaja autentimine.

Kasutage ainult üht laadijat. SDK tunneb ära ülaltoodud markeri, mitte iga käsitsi lisatud sama src-iga skripti. Avaldatud SDK 0.1.4 jagab viiteid ainult identsete mountWidget() valikute korral ning lükkab muudetud võtme, lõpp-punkti, skripti URL-i, locale’i või silumise sätte tagasi, kuni kõik handle’id on eemaldatud. Vidin ei jälgi juhtpaneeli konfiguratsioonimuudatusi; salvestatud sätete rakendamiseks lähtestage see uuesti. Praeguse lähtekoodi hostitud widget.js v16 võib <html lang>-i või data-locale-i muutumisel vidina enda süsteemseid silte värskendada, kui lahendatud locale muutub ja projekti keelepoliitika seda lubab. Enne reaalajas saidil sellisele uuendusele tuginemist kontrollige laadija juurutatud versiooni; see käitumine ei kuulu avaldatud npm SDK 0.1.4-le. Kasutaja kirjutatud pealkirja, tervitusteksti ega loodud vastuseid ei tõlgita automaatselt.

Puhas HTML

Kleepige koodilõik üks kord body lõpu lähedale, vahetult enne </body>. See töötab staatilise HTML-i, käsitsi kodeeritud saitide ja globaalse jalusega mallide puhul.

<!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 / Reacti rakenduse shell

Next.js App Routeri saidi puhul lisage vidin faili app/layout.tsx koos next/script-iga, et see laaditaks kogu rakenduse jaoks üks kord.

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>
  );
}

Reacti üheleherakenduse puhul lisage skript üks kord rakenduse ülemise taseme shell’i või HTML-malli. Ärge lisage seda iga marsruudi komponendist.

Tavalisel navigeerimisel hoidke laadijat rakenduse püsivas shell’is. Kui soovite selle marsruudi vahetamisel või nõusoleku tühistamisel eemaldada, eemaldage kõik SDK 0.1.4 handle’id: viimane sobiv handle annab hostitud widget.js v15-le märku oma kasutajaliidese ja stiilide hävitamiseks ning ootel algkäivituse, korduskatsete (kuni 10 katset 30 sekundi jooksul) ja käimasoleva vestluse tühistamiseks. window.ChattyBox.destroy() on saadaval pärast v15 algkäivitust. Teardown ei saa tagasi võtta päringut, mida server on juba töödelnud. Hostitud vidin paigutatakse document.body alla, mitte seda laadiva komponendi sisse.

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

Docusauruse puhul looge või uuendage faili src/theme/Root.tsx, et vidin oleks kõigil dokumentatsioonilehtedel saadaval.

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}</>;
}

Kui teie Docusauruse saidil on tõlgitud marsruudid, määrake data-locale enne laadimist (kui projekt lubab skripti ülekirjutust) või valige Tuvasta automaatselt ja kasutage lehe <html lang> väärtust. Valik Fikseeritud kasutab projekti vaike-locale’i, kui skripti ülekirjutus pole lubatud. Praeguse lähtekoodi hostitud widget.js v16 võib lahendatud locale’i muutumisel vidina enda süsteemseid silte värskendada, kui projekti keelepoliitika seda lubab; enne sellele värskendusele tuginemist kontrollige laadija juurutatud versiooni. See käitumine puudutab hostitud vidinat, mitte avaldatud npm SDK-d 0.1.4. Kohandatud pealkirja, tervitusteksti ega loodud vastuseid ei tõlgita automaatselt.

Hoidke laadija püsivas rakenduse shell’is. Ärge looge seda tavaliste kliendipoolsete marsruudimuudatuste ajal uuesti; sihipäraseks eemaldamiseks kasutage hostitud vidina hävitamise API-t või eemaldage kõik SDK mount-käepidemed, kui kasutasite SDK-d.

Kohandatud kasutajaliides

Hostitud vidin on valikuline. Kui soovite täielikku kontrolli renderdamise, sõnumiolekute ja interaktsioonidisaini üle, kasutage JavaScripti SDK-d sama avaliku vidina API-võtme ja vidina API URL-iga.

Üldine CMS / kohandatud HTML

Enamikul CMS-platvormidel on globaalne kohandatud koodi, jaluse või teema malli ala. Lisage skript sinna, et iga avalik leht saaks vidina laadida.

Kasutage seda teed Webflow, Frameri, Squarespace’i, Wixi kohandatud koodialade, Shopify teemade, HubSpoti mallide ja kohandatud CMS-platvormide puhul, mis lubavad globaalset HTML-i muuta.

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

Enne avaldamist kontrollige, et CMS ei eemaldaks kohandatud skriptidest data-api-key-i, data-api-url-i ega async-i.

Google Tag Manager

Kasutage Google Tag Manageri, kui teie meeskond haldab kolmanda osapoole skripte juba GTM-i kaudu.

1. Avage oma GTM-i konteiner.
2. Looge uus Custom HTML-silt.
3. Kleepige ChattyBoxi koodilõik.
4. Kasutage All Pages-i käivitajat või kitsamat käivitajat ainult lehtede jaoks, kus vidin peab ilmuma.
5. Vaadake konteineri eelvaadet, kontrollige vidina laadimist ja avaldage seejärel.

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

Kui sait kasutab nõusolekurežiimi või sildi nõusolekupoliitikat, veenduge, et vidinal oleks lubatud laadida lehtedel, kus külastajad abi vajavad.

Sisuturbe poliitika (CSP)

Vaikimisi hostitud laadija jaoks lubage https://chattybox.ai direktiivis script-src ja vidina API origin direktiivis connect-src. Vidin lisab stiililehe ja tekstisisesed stiiliatribuudid; sellel pole praegu nonce’i valikut, seega tekstisiseseid stiile keelav poliitika blokeerib osa kasutajaliidest. Kui poliitika seda lubab, lisage nende stiilide jaoks 'unsafe-inline' või kasutage oma CSP-ga ühilduvat kasutajaliidest. Interi fonti laaditakse käivitaja avamisel; selleks lubage https://fonts.googleapis.com direktiivis style-src ja https://fonts.gstatic.com direktiivis font-src. Lubage direktiivis img-src ka konfigureeritud ikoonipildi origin. Enne CSP leevendamist arvestage nõusoleku- ja turvanõuetega.

WordPressi plugina juhend

Koodivabaks WordPressi paigalduseks kasutage ChattyBoxi WordPressi pluginat. Plugina paigaldamiseks, konfigureerimiseks, marsruutide välistamiseks ja kontrollimiseks järgige WordPressi plugina juhendit. Tootmise API lõpp-punkt konfigureeritakse automaatselt.

Plugin laadib hostitud vidina avaliku esiosa päringutel ilma teemat muutmata. See ei laadi vidinat tahtlikult wp-adminis, voogudes, REST-päringutes ega AJAX-päringutes.

See ei kontrolli iga esikülje lehe privaatsust ega juurdepääsu. Vajaduse korral rakendage ja testige ostukorvi/makse-, konto-, parooliga kaitstud või liikmesuslehtede välistusi plugina filtri abil või kasutage sobiva ulatusega käsitsi paigaldust.

Plugina laadija URL-i seade ei muuda sisseehitatud tootmise API lõpp-punkti; teise API juurutuse jaoks kasutage käsitsi lisatavat koodilõiku.

Kui eelistate käsitsi skripti paigaldamist, kasutage üht WordPressi seadistuses juba toetatud skripti asukohta:

• Teema seaded, mis pakuvad päise- või jaluseskripte.
• Lapsteema, mis juhib jaluse malli.
• Päise/jaluse skripti plugin.
• Google Tag Manager, kui teie WordPressi sait seda juba kasutab.

Paigutage koodilõik globaalsesse jaluse asukohta, et see ilmuks avaldatud lehtedel, postitustel, dokumentidel ja teadmistebaasi artiklitel, kus vestlusrobot peab saadaval olema.

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

Vältige vidina lisamist wp-admini, kassasse, konto- või privaatse liikmelisuse lehtedele, välja arvatud juhul, kui need lehed on tahtlikult avalikud ja toetatud.

Drupali moodul

Drupal 10 või 11 puhul on Composer soovituslik paigaldusviis. Moodulit levitatakse praegu avaliku GitHubi hoidla märgistatud paketina. Seda ei ole veel Drupal.org-is ega Packagistis loetletud, seega lisage seda kasutava Drupali projekti juurkausta composer.json-i avalik GitHubi VCS-hoidla:

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

Seejärel installige märgistatud moodul ja lubage see:

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

Avage Configuration > Web services > ChattyBox, kleepige projekti vahekaardilt Veebisaidi paigaldamine avalik vidina API-võti ja lubage vestlusrobot. Moodul on algselt keelatud. Kohalikult kontrollitud mooduliversioonis on API lõpp-punkt koodi sisse kirjutatud. Võrrelge seda oma koodilõiguga; teise API juurutuse jaoks kasutage käsitsi integratsiooni. Marsruutide välistamise ja käsitsi varuvariandi kohta lugege Drupali vestlusroboti mooduli juhendist.

Moodul jätab vahele halduspäringud ja päringud, mille Drupali päringuvorming ei ole HTML, kuid ei kontrolli kogu privaatset esikülje sisu. Skripti URL-i muutmine ei muuda sisseehitatud tootmise API lõpp-punkti. Teise API juurutuse jaoks kasutage mooduli asemel käsitsi lisatavat vidinakoodilõiku.

Kontrollimine

Pärast paigaldamist läbige enne vestlusroboti väljakuulutamist käivitamise kontrollnimekiri:

• Avage avalik leht inkognitoaknas.
• Kontrollige, et vidina avaja ilmuks.
• Avage vidin ja esitage päris kliendiküsimus.
• Kontrollige, et toetatud vastus sisaldaks asjakohaseid allikaviiteid, seejärel esitage toetamata küsimus ja kontrollige varuvastust (sellel ei pruugi allikaid olla).
• Kontrollige brauserikonsoolist puuduvaid data-api-key-i või data-api-url-i ning võtmevigu. Vaadake üle ka võtme origin’i seaded: kas piirang on sisse lülitatud ja kas soovitud juurutuse origin on lubatud. Paigaldust ette valmistades loodud võti võib juba olla piiratud.

SPA puhul takistab kitsam GTM-käivitaja vidina esialgset laadimist välistatud marsruutidel, kuid ei eemalda muul marsruudil juba laaditud vidinat. Ärge käivitage laadijat korduvalt ajaloo muutumisel.