Canllawiau Gosod

:::note Statws fersiwn Mae'r SDK npm 0.1.4 cyhoeddedig yn cyfrif cyfeiriadau mountiau unfath. Pan dynnir yr handlen olaf sy'n cyfateb, gall widget.js v15 lletyol ddinistrio'i UI a chanslo gwaith sydd ar y gweill; mae window.ChattyBox.destroy() ar gael ar ôl cychwyn v15. :::

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 Profi'r sgwrsfot.

Paratowch osodiad ar gyfer eich gwefan neu reolwch allwedd sy’n ddiogel i’r porwr o dan Gosod → Allweddi a pharthau. Gwiriwch osodiadau tarddiad yr allwedd: gall allwedd a baratowyd ar gyfer gwefan fod eisoes wedi’i chyfyngu i’r tarddiad hwnnw, tra bo allweddi heb gyfyngiadau’n gweithio ar draws tarddiadau. O dan Golygu tarddiadau, gallwch alluogi cyfyngiadau dewisol neu ychwanegu’r tarddiadau cynhyrchu, rhagolwg, llwyfannu a localhost sydd eu hangen arnoch. Pan fydd wedi’i alluogi, mae’r cyfatebiaeth yn cynnwys cynllun, enw gwesteiwr a phorth yn union: mae https://example.com, https://preview.example.com a http://localhost:3000 yn gofnodion ar wahân. O dan Gosod ar wefan, 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>

O dan Gosod → Gosod ar wefan, rhowch URL gwefan HTTP(S) yn gyntaf. Mae’r dewiswr yn cynnig allweddi sydd heb ddod i ben ac sydd naill ai heb gyfyngiad neu wedi’u caniatáu ar gyfer tarddiad yr URL. I ddewis allwedd gyfyngedig, rhowch darddiad a ganiateir; archwiliwch ei chyfyngiadau drwy Rheoli allweddi a pharthau a ganiateir. Os nad yw’r ffurflen ar gael, cwblhewch y cam paratoi a ddangosir yn y dangosfwrdd yn gyntaf.

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; argymhellir wrth fewnosod o god rhaglen.
data-debug="true"	Nac oes	Galluogi diagnosteg porwr; wedi'i ddiffodd yn ddiofyn.
data-color	Nac oes	Diystyru lliw acen yn benodol ar ôl nôl config llwyddiannus; defnyddiwch werth hecs chwe digid. Mae'n well defnyddio'r dangosfwrdd.
data-position	Nac oes	Diystyru safle yn benodol ar ôl nôl config llwyddiannus: bottom-right, bottom-left, top-right neu top-left. Mae'n well defnyddio'r dangosfwrdd.

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 Gosod → Allweddi a pharthau a Golygu tarddiadau 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.

Gosodwch un loader yn unig. Mae'r SDK yn adnabod y priodoledd marciwr uchod, nid pob sgript â llaw sydd â'r un src. Yn y SDK cyhoeddedig 0.1.4, dim ond opsiynau mount unfath sy'n cael eu cyfrif gyda'i gilydd; gwrthodir allwedd, endpoint, URL sgript, locale neu osodiad debug sydd wedi newid nes tynnu pob handlen. Nid yw'r widget yn tanysgrifio i newidiadau cyfluniad y dangosfwrdd; ailgychwynnwch ef i lwytho gosodiadau sydd wedi'u cadw. Yng nghod cyfredol y widget.js v16 lletyol, gall newid <html lang> neu data-locale y loader adnewyddu labeli'r widget pan fydd y locale wedi'i ddatrys yn newid, yn amodol ar bolisi iaith y prosiect. Gwiriwch fersiwn y loader sydd wedi'i defnyddio cyn dibynnu ar ddiweddariadau byw; mae'r ymddygiad hwn ar wahân i fersiwn yr SDK npm cyhoeddedig. Pan fydd cyfyngiadau tarddiad wedi'u galluogi, defnyddir Origin neu darddiad wrth gefn o Referer; mae tarddiadau coll neu nas caniateir yn rhoi 401 Invalid API key. Nid dilysu yw'r cyfyngiadau hyn.

Gall URL API fod yn wraidd deployment HTTP neu orffen â /chat; mae’r loader yn tynnu slash terfynol a /chat cyn deillio endpointau. Nid yw’n trosi URL Convex .cloud yn .site. Peidiwch â chynnwys query string na fragment yn y gwerth hwn.

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"
          data-chattybox-widget="true"
          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.

Cadwch y loader mewn plisgyn ap parhaus yn ystod llywio arferol. Ar gyfer tynnu bwriadol neu ddirymu caniatâd, galwch remove() ar bob handle o’r SDK npm 0.1.4; mae’r handle cyfatebol olaf yn hysbysu widget.js v15 lletyol i ddinistrio’r rhyngwyneb a’r arddulliau y mae’n berchen arnynt a chanslo cychwyn, ailgeisiadau (hyd at 10 mewn 30 eiliad) a sgwrs sydd ar y gweill. Mae window.ChattyBox.destroy() hefyd ar gael ar ôl cychwyn v15. Nid yw tynnu elfen <script> yn unig yn dileu UI sydd eisoes wedi’i rendro; ni all glanhau ddadwneud cais a broseswyd gan y gweinydd. Mae’r widget lletyol yn arnofio o dan document.body, nid y gydran sy’n ei lwytho.

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 llwytho pan ganiateir diystyru, neu defnyddiwch Auto a <html lang> y dudalen. Mae modd Sefydlog yn defnyddio locale diofyn y prosiect oni bai bod diystyriad sgript a ganiateir yn bresennol. Yng nghod cyfredol y widget.js v16 lletyol, gall labeli UI adnewyddu pan fydd newid i’r naill briodoledd yn newid y locale a ddatryswyd; gwiriwch fersiwn y loader sydd wedi’i defnyddio cyn dibynnu ar hyn. Ni chaiff testun teitl a neges groeso wedi’u haddasu nac atebion a gynhyrchir eu cyfieithu’n awtomatig.

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; defnyddiwch API dinistrio'r widget lletyol pan fydd angen ei dynnu'n fwriadol, neu tynnwch bob handlen mount os defnyddiwyd y SDK.

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. Peidiwch â sbarduno'r llwythwr dro ar ôl tro wrth i'r hanes newid.

Content Security Policy

Ar gyfer y loader lletyol diofyn, caniatewch https://chattybox.ai yn script-src a tharddiad API y widget yn connect-src. Mae’r widget yn chwistrellu dalen arddull a phriodoleddau arddull mewnol; nid oes ganddo opsiwn nonce ar hyn o bryd, felly bydd polisi sy’n gwahardd arddulliau mewnol yn rhwystro rhannau o’r UI. Os yw’ch polisi’n caniatáu hynny, caniatewch 'unsafe-inline' ar gyfer yr arddulliau hyn neu defnyddiwch UI personol sy’n gydnaws â’r polisi. Mae llwytho Inter wrth ryngweithio â’r lansiwr hefyd yn gofyn am https://fonts.googleapis.com yn style-src a https://fonts.gstatic.com yn font-src. Caniatewch darddiad delwedd yr eicon wedi’i ffurfweddu yn img-src. Adolygwch ofynion caniatâd a diogelwch cyn llacio CSP.

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. Pan fo angen, gweithredwch a phrofwch eithriadau ar gyfer checkout, account, tudalennau a ddiogelir gan gyfrinair neu aelodaeth drwy hidlydd yr ategyn, neu defnyddiwch osodiad â llaw sydd â chwmpas priodol. Nid yw gosodiad URL loader yr ategyn yn newid ei endpoint API cynhyrchu adeiledig; defnyddiwch byt â 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’r pyt yn Gosod ar wefan a galluogwch y chatbot. Mae’r fersiwn o’r modiwl a archwiliwyd yn lleol yn defnyddio endpoint API wedi’i godio’n galed. Cymharwch ef â’ch pyt a defnyddiwch integreiddiad â llaw ar gyfer deployment API gwahanol. Gweler canllaw modiwl chatbot Drupal am eithriadau llwybrau, caching, caniatâd a’r opsiwn wrth gefn â llaw.

Mae’r modiwl wedi’i analluogi yn ddiofyn. Mae’n hepgor ceisiadau gweinyddol a cheisiadau nad ydynt yn HTML, nid yr holl gynnwys preifat ar y frontend. Nid yw newid URL y sgript yn newid yr endpoint API cynhyrchu adeiledig. Defnyddiwch byt widget â llaw yn lle’r modiwl os oes angen deployment API gwahanol arnoch.

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.

Wrth wirio’r gosodiad, gwiriwch osodiadau tarddiad yr allwedd hefyd: a yw cyfyngiad wedi’i alluogi ac a ganiateir y tarddiad rydych yn ei brofi. Gall allwedd a baratowyd ar gyfer gosodiad fod eisoes wedi’i chyfyngu.

Llwythwch un loader yn unig ar bob tudalen. Nid yw’r widget yn tanysgrifio i newidiadau ffurfweddu’r dangosfwrdd sydd wedi’u cadw; ailgychwynnwch ef i lwytho’r gosodiadau sydd wedi’u cadw. Yng nghod cyfredol y widget.js v16 lletyol, gall labeli sy’n perthyn i’r cynnyrch adnewyddu wrth newid locale fel y disgrifir uchod, ond gwiriwch y fersiwn sydd wedi’i defnyddio cyn dibynnu ar hynny. Ni chaiff testun teitl a neges groeso wedi’u haddasu nac atebion a gynhyrchir eu cyfieithu’n awtomatig. Gwiriwch a yw cyfyngiadau tarddiad yr allwedd wedi’u galluogi ac, os felly, a ganiateir y tarddiad rydych yn ei brofi. Gall allwedd a baratowyd ar gyfer gosodiad fod wedi’i chyfyngu eisoes; mae’r cyfatebiad yn union yn ôl cynllun, gwesteiwr a phorth, ac nid yw’n ddilysu.