Canllawiau Gosod

:::note Statws fersiwn Mae'r SDK npm 0.1.4 cyhoeddedig gyda widget.js v15 yn cefnogi teardown drwy remove() neu window.ChattyBox.destroy() ac yn canslo gwaith sydd ar y gweill. :::

Mae’r integreiddiad widget.js lletyol yn llwybr heb adeiladu pan fyddwch am i ChattyBox gynnal y rhyngwyneb a’r cludiant. Os dylai eich ap gychwyn yr un UI o god npm, defnyddiwch mountWidget(). I fod yn berchen ar yr UI, defnyddiwch y SDK di-ben.

Cyn Gosod

Cwblhewch lif Dechrau Arni yn gyntaf: ffurfweddwch a sgrapiwch y ffynhonnell, adolygwch dudalennau wedi’u mynegeio, a gwiriwch atebion cynrychioliadol yn Test Chat.

Yna crëwch allwedd sy’n ddiogel i’r porwr yn Public Keys. Mae'n gweithio ar draws tarddiadau cynhyrchu, rhagolwg/llwyfannu a localhost yn ddiofyn. I ychwanegu caledu ychwanegol dewisol fel amddiffyniad mewn dyfnder, dewiswch Edit origins, galluogwch Restrict this key to specific origins, ac ychwanegwch y tarddiadau a ganiateir yn union. Pan fydd wedi'i alluogi, mae'r cyfatebiaeth yn cynnwys cynllun, enw gwesteiwr a phorth: mae https://example.com, https://preview.example.com a http://localhost:3000 yn gofnodion ar wahân. Dychwelwch i Embed, dewiswch yr allwedd, a chopïwch y pyt a gynhyrchir. Mae’n cynnwys yr allwedd gyhoeddus a’r URL API ar gyfer eich prosiect:

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

Am lwyfannau sy’n canolbwyntio ar ddogfennaeth, gweler y canllawiau chatbot AI MkDocs, chatbot AI VitePress a chatbot AI GitBook.

Disodlwch YOUR_API_KEY ag allwedd widget gyhoeddus eich dangosfwrdd. Cadwch werth data-api-url yn union fel y’i dangosir yn y dangosfwrdd. Wrth gynhyrchu, URL sefydlog https://...convex.site/chat ar gyfer API widget cyhoeddus yw hwn.

Beth Sy’n Perthyn i’r Sgript

Defnyddiwch briodoleddau sgript ar gyfer gwerthoedd y mae’n rhaid iddynt fod ar gael cyn y gall y widget ddechrau:

Priodoledd	Angenrheidiol	Defnyddiwch ef ar gyfer
src	Oes	Llwytho JavaScript y widget ChattyBox.
data-api-key	Oes	Nodi allwedd widget gyhoeddus eich prosiect.
data-api-url	Oes	Anfon ceisiadau widget at API ChattyBox.
data-locale	Nac oes	Gofyn am iaith UI wrth gychwyn, dim ond os yw’r prosiect yn caniatáu diystyru sgript.
data-chattybox-widget="true"	Nac oes	Galluogi loader deinamig a’r SDK i ganfod sgript sy’n bodoli.
data-debug="true"	Nac oes	Galluogi diagnosteg porwr.
data-color	Nac oes	Diystyru lliw acen ar ôl nôl config llwyddiannus; defnyddiwch hex chwe digid.
data-position	Nac oes	Diystyru safle ar ôl nôl config llwyddiannus; mae pob un o'r pedair cornel yn cael eu cefnogi.

Defnyddiwch osodiadau’r dangosfwrdd ar gyfer popeth y dylid ei reoli heb ail-ddefnyddio eich gwefan:

• Lliwiau, safle, eicon, teitl a neges groeso’r widget.
• Modd iaith diofyn ac a ganiateir diystyru data-locale.
• Creu a dileu allweddi cyhoeddus, ac unrhyw gyfyngiadau tarddiad dewisol fesul allwedd. Agorwch Public Keys > Edit origins i alluogi cyfyngiad ac ychwanegu neu ddileu tarddiadau cynhyrchu, llwyfannu, rhagolwg neu localhost.
• Sgrapio, ail-sgrapio, sgwrs brawf, dadansoddeg a bylchau cynnwys.

Os ydych yn galluogi’r clo config-as-code, daw gosodiadau’r cynorthwyydd, ffynhonnell, runtime a widget a gefnogir o’r ffurfweddiad a ddefnyddiwyd yn lle ffurflenni’r dangosfwrdd. Mae allweddi cyhoeddus a tharddiadau a ganiateir yn parhau’n osodiadau prosiect, nid yn werthoedd ffeil ffurfweddu.

Gall URL API fod yn wraidd deployment HTTP neu orffen â /chat; mae'r loader yn tynnu slash terfynol a /chat, ond nid yw'n trosi .convex.cloud yn .site. Peidiwch â chynnwys query na fragment. Gosodwch un loader yn unig. Yn y SDK cyhoeddedig 0.1.4, mae mountiau unfath yn rhannu'r sgript a chyfeiriad; mae remove() yn idempotent, a dim ond yr handlen olaf sy'n signalau teardown v15 llawn o UI, arddulliau, ffontiau, gwaith sydd ar y gweill, sgript ac API byd-eang. Gwrthodir opsiynau gwahanol tra bo handlenni'n bodoli.

HTML Plaen

Gludwch y pyt unwaith ger diwedd body, ychydig cyn </body>. Mae hyn yn gweithio ar gyfer HTML statig, gwefannau wedi’u codio â llaw a thempledi sy’n darparu troedyn byd-eang.

<!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 App Shell

Ar gyfer gwefan Next.js App Router, ychwanegwch y widget at app/layout.tsx gyda next/script fel ei fod yn llwytho unwaith ar gyfer yr ap cyfan.

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

Ar gyfer ap React un dudalen, ychwanegwch y sgript unwaith yn eich plisgyn ap lefel uchaf neu dempled HTML. Peidiwch â’i chwistrellu o bob cydran llwybr.

Mae'r enghreifftiau shell parhaus yn fwriadol heb cleanup sy'n tynnu sgript. Mae'r widget yn arnofio o dan document.body, nid y gydran sy'n ei llwytho.

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

Ar gyfer Docusaurus, crëwch neu diweddarwch src/theme/Root.tsx fel bod y widget ar gael ar draws tudalennau dogfennaeth.

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

Ar lwybrau Docusaurus wedi’u cyfieithu, gosodwch data-locale cyn y loader dim ond gyda diystyru a ganiateir, neu defnyddiwch Auto a <html lang>. Mae Fixed yn defnyddio’r diofyn ac nid yw locale yn newid ar lwybr SPA newydd.

Cadwch y llwythwr yn eich plisgyn rhaglen parhaus. Peidiwch â’i ail-greu na’i dynnu yn ystod newidiadau arferol i lwybrau ar ochr y cleient.

Rhyngwyneb Personol

Mae’r widget lletyol yn ddewisol. Os ydych am gael rheolaeth lawn dros rendro, cyflwr negeseuon a chynllun rhyngweithio, defnyddiwch y SDK JavaScript gyda’r un allwedd API widget gyhoeddus ac URL API widget.

CMS Cyffredinol/HTML Personol

Mae gan y rhan fwyaf o lwyfannau CMS ardal cod personol byd-eang, troedyn neu dempled thema. Ychwanegwch y sgript yno fel y gall pob tudalen gyhoeddus lwytho’r widget.

Defnyddiwch y llwybr hwn ar gyfer Webflow, Framer, Squarespace, ardaloedd cod personol Wix, themâu Shopify, templedi HubSpot a llwyfannau CMS personol sy’n gadael i chi olygu HTML byd-eang.

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

Cyn cyhoeddi, cadarnhewch nad yw’r CMS yn tynnu data-api-key, data-api-url nac async o sgriptiau personol.

Google Tag Manager

Defnyddiwch Google Tag Manager pan fydd eich tîm eisoes yn rheoli sgriptiau trydydd parti drwy GTM.

1. Agorwch eich cynhwysydd GTM.
2. Crëwch dag Custom HTML newydd.
3. Gludwch byt ChattyBox.
4. Defnyddiwch sbardun All Pages, neu sbardun culach ar gyfer y tudalennau a ddylai ddangos y widget yn unig.
5. Rhagolygwch y cynhwysydd, gwiriwch fod y widget yn llwytho, yna cyhoeddwch.

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

Os yw eich gwefan yn defnyddio modd caniatâd neu bolisi caniatâd tagiau, sicrhewch fod y widget yn cael llwytho ar y tudalennau lle mae angen cymorth ar ymwelwyr.

Ar SPA, mae sbardun GTM culach yn atal y llwyth cyntaf ar lwybrau a eithrir, ond nid yw'n tynnu widget sydd eisoes wedi'i lwytho ar lwybr arall.

Canllaw ategyn WordPress

Ar gyfer gosodiad WordPress heb god, defnyddiwch ategyn WordPress ChattyBox. Dilynwch y canllaw ategyn WordPress i'w osod, ei ffurfweddu, eithrio llwybrau a'i ddilysu. Caiff endpoint API cynhyrchu ei ffurfweddu'n awtomatig.

Mae'r ategyn yn llwytho'r widget lletyol ar geisiadau frontend cyhoeddus heb olygu'ch thema. Nid yw'n llwytho'n fwriadol yn wp-admin, ffrydiau, ceisiadau REST nac AJAX.

Nid yw hwn yn wiriad preifatrwydd/mynediad ar bob tudalen frontend: eithriwch checkout, cyfrif, cyfrinair neu dudalennau aelodaeth yn fwriadol. Nid yw gosodiad URL loader yr ategyn yn newid ei endpoint API cynhyrchu adeiledig; defnyddiwch pyt â llaw ar gyfer deployment API arall.

Os yw'n well gennych osod sgript â llaw, defnyddiwch un o'r lleoliadau sgript y mae eich gosodiad WordPress eisoes yn eu cefnogi:

• Gosodiadau thema sy’n darparu sgriptiau pennyn neu droedyn.
• Thema blentyn sy’n rheoli templed y troedyn.
• Ategyn sgript pennyn/troedyn.
• Google Tag Manager os yw eich gwefan WordPress eisoes yn ei ddefnyddio.

Gludwch y pyt mewn lleoliad troedyn byd-eang fel ei fod yn ymddangos ar dudalennau, postiadau, dogfennau ac erthyglau cronfa wybodaeth cyhoeddedig lle dylai'r chatbot fod ar gael.

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

Ceisiwch osgoi ychwanegu’r widget at wp-admin, checkout, account neu dudalennau aelodaeth breifat oni bai bod y tudalennau hynny’n gyhoeddus ac wedi’u cefnogi’n fwriadol.

Modiwl Drupal

Ar gyfer Drupal 10 neu 11, Composer yw’r llwybr gosod a argymhellir. Ychwanegwch y storfa VCS GitHub gyhoeddus at composer.json gwraidd y prosiect Drupal sy’n ei defnyddio:

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

Yna gosodwch y modiwl wedi’i dagio a’i alluogi:

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

Agorwch Configuration > Web services > ChattyBox, gludwch allwedd API gyhoeddus y widget o dab Embed y prosiect a galluogwch y chatbot. Caiff endpoint API cynhyrchu ei ffurfweddu’n awtomatig. Gweler ganllaw modiwl chatbot Drupal am eithriadau llwybrau a’r opsiwn wrth gefn â llaw.

Dilysu

Ar ôl gosod, rhedwch y rhestr wirio lansio cyn cyhoeddi’r chatbot:

• Agorwch dudalen gyhoeddus mewn ffenestr incognito.
• Cadarnhewch fod lansiwr y widget yn ymddangos.
• Agorwch y widget a gofynnwch gwestiwn cwsmer go iawn.
• Gwiriwch fod ateb a gefnogir yn cynnwys dyfyniadau ffynhonnell perthnasol, yna gofynnwch gwestiwn heb gefnogaeth a gwiriwch fallback a all fod heb ffynonellau.
• Gwiriwch gonsol y porwr am data-api-key coll, data-api-url coll, neu wallau allwedd/tarddiad.