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 kraapige allikas, vaadake indekseeritud lehed üle ning kontrollige tüüpilisi vastuseid Test Chat-is.

Seejärel looge jaotises Public Keys brauseris turvaline võti. See töötab tootmises, eelvaates, testkeskkonnas ja localhostis vaikimisi. Valikulise lisakaitse jaoks avage Edit origins, lubage Restrict this key to specific origins ja lisage täpsed lubatud origin’id; skeem, hostinimi ja port peavad kõik ühtima. Naaske jaotisse Embed, valige võti, lõpetage hostitud vidina kohandamine ja kopeerige loodud koodilõik. See 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.
`data-debug="true"`	Ei	Lülitab sisse brauseri diagnostika; vaikimisi väljas.
`data-color`, `data-position`	Ei	Alistavad pärast edukat seadistuse päringut värvi või asukoha; eelistage juhtpaneeli.

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

Vidina värvid, asukoht, ikoon, pealkiri ja tervitussõnum.
Vaikekeelerežiim ja see, kas data-locale-i ülekirjutused on lubatud.
Avalike võtmete loomine ja kustutamine ning projektile seadistatud lubatud origin’ide piirangud.
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 seadistuse juurdepääsumandaatideks, mitte konfiguratsioonifaili väärtusteks.

Kasutage üht laadijat. Widget loeb seadistuse ja tõlked algkäivitamisel ega jälgi juhtpaneeli ega lehe keele hilisemaid muutusi; salvestatud seadete kasutamiseks laadige leht uuesti. Kui origin’i piirang on lubatud, kasutab kontroll Origin-it või Referer-i origin’it ning puuduva või keelatud origin’i korral tagastatakse 401 Invalid API key.

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. Avaldatud SDK-s 0.1.4 jagavad identsed mountid skripti ja viidet; remove() on idempotentne ning ainult viimane käepide signaliseerib v15 teardowni, mis eemaldab UI, stiilid, fondid, skripti ja globaalse API ning katkestab ootel töö. Erinevad valikud lükatakse tagasi, kuni käepidemeid 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

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 override’id on lubatud) või kasutage Auto-režiimi ja lehe <html lang> väärtust. Fixed-režiim kasutab projekti vaikimisi lokaati, kui lubatud override’i pole. Lokaal määratakse ainult algkäivitamisel, mitte kliendipoolsel marsruudimuutusel; uue lehekeele kasutamiseks tehke täislehe laadimine.

Hoidke laadija püsivas rakenduse shell’is. Ärge looge ega eemaldage seda tavaliste kliendipoolsete marsruudimuudatuste ajal.

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.

Avage oma GTM-i konteiner.
Looge uus Custom HTML-silt.
Kleepige ChattyBoxi koodilõik.
Kasutage All Pages-i käivitajat või kitsamat käivitajat ainult lehtede jaoks, kus vidin peab ilmuma.
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.

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.

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 Embed avalik vidina API-võti ja lubage vestlusrobot. Tootmise API lõpp-punkt konfigureeritakse automaatselt. Marsruutide välistamise ja käsitsi varuvariandi kohta lugege Drupali vestlusroboti mooduli juhendist.

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 vastus sisaldaks allikaviiteid.
Kontrollige brauserikonsooli puuduva data-api-key-i, puuduva data-api-url-i või võtme/origin’i vigade suhtes. Kui sait kasutab CSP-d, lubage vaikelaadija jaoks script-src-is https://chattybox.ai ja connect-src-is oma vidina API origin. Vidin lisab stiile; praegu nonce’i valikut pole. Kitsama GTM-päästiku korral ei eemaldata SPA-s juba teisel marsruudil laaditud vidinat ning loaderit ei tohi history-muutustel korduvalt käivitada.

Enne paigaldamist​

Mis kuulub skripti​

Puhas HTML​

Next.js / Reacti rakenduse shell​

Docusaurus​

Kohandatud kasutajaliides​

Üldine CMS / kohandatud HTML​

Google Tag Manager​

WordPressi plugina juhend​

Drupali moodul​

Kontrollimine​

Privaatsusvalikud