Asennusoppaat

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 ja rajoita sen sallitut origin-osoitteet. 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	Widgetin käyttöliittymän kielen pakottaminen tietyllä sivulla.

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ä projektille määritetyt sallitun originin rajoitukset.
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.

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"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

Lisää Reactin yhden sivun sovelluksessa skripti kerran ylimmän tason sovellusshelliin tai HTML-malliin. Älä lisää sitä jokaisesta reittikomponentista.

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.

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.

WordPress

ChattyBox ei tarvitse WordPress-lisäosaa. Käytä jotakin skriptin sijaintia, jota WordPress-asetuksesi jo tukee:

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 alatunnisteeseen, jotta se näkyy julkaistuilla sivuilla, artikkeleissa, dokumenteissa ja tietämyskannan artikkeleissa, joissa chatbotin tulee 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.

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ä vastaus sisältää lähdeviitteitä.
Tarkista selaimen konsolista puuttuva data-api-key, puuttuva data-api-url tai avain-/origin-virheet.

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​

Vahvistus​

Privacy choices