CDN / תג סקריפט

גרסת ה-CDN כוללת את React באופן פנימי, כך שתוכלו להשתמש בווידג’ט באתרים סטטיים, ב-WordPress, ב-Webflow או בכל דף שבו תוכלו להוסיף HTML. אין צורך ב-npm, בכלי bundler או במסגרת עבודה.

כתובות URL של CDN

<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>

<!-- Each stable release also publishes an immutable /widget/vX.Y.Z/ path
     matching the @thunderphone/widget npm version (v1.1.2 at the time of
     writing). If you pin, you own updating the URL for new releases. -->
<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/v1.1.2/style.css" />
<script src="https://cdn.thunderphone.com/widget/v1.1.2/widget.js"></script>

כתובות ה-URL של latest הן אלו שמחולל מקטע ההטמעה בלוח הבקרה יוצר. הן נשמרות במטמון למשך 5 דקות ומקבלות מהדורות יציבות חדשות באופן אוטומטי. נתיבי /widget/vX.Y.Z/ מקובעים אינם ניתנים לשינוי ונשמרים במטמון לטווח ארוך — אם אתם מקבעים גרסה, התאימו אותה למהדורת npm של @thunderphone/widget שמולה אתם מפתחים.

שימוש בסיסי

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
</head>
<body>

  <div id="thunderphone"></div>

  <script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
  <script>
    ThunderPhone.mount({
      element: '#thunderphone',
      publishableKey: 'pk_live_your_publishable_key',
    })
  </script>

</body>
</html>

הווידג’ט נטען לתוך רכיב היעד ומוצג כ-סרגל במיקום קבוע באחת מפינות אזור התצוגה (ברירת המחדל היא bottom-right, ונשלטת באמצעות האפשרות position). רכיב הטעינה הוא רק שורש ה-React — מיקומו בדף אינו משפיע על המקום שבו הווידג’ט מופיע.

אפשרויות טעינה

ThunderPhone.mount() מקבלת את אותן אפשרויות כמו רכיב ה-React, בנוסף למאפיין element:

אפשרות	סוג	חובה	ברירת מחדל	תיאור
`element`	`string \| HTMLElement`	כן	—	בורר CSS (לדוגמה, `'#thunderphone'`) או הפניה לרכיב DOM.
`publishableKey`	`string`	כן	—	מפתח API לפרסום (`pk_live_...`). הסוכן מזוהה אוטומטית מתצורת הווידג’ט של המפתח.
`theme`	`'light' \| 'dark'`	לא	`'light'`	ערכת צבעים.
`primaryColor`	`string`	לא	`'#000000'` (בהיר) / `'#ffffff'` (כהה)	מחרוזת צבע CSS המשמשת כצבע הדגשה.
`title`	`string`	לא	`'Voice assistant'`	הטקסט שמוצג בסרגל הווידג’ט.
`position`	`'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'`	לא	`'bottom-right'`	מיקום קבוע באזור התצוגה.
`apiBase`	`string`	לא	`'https://api.thunderphone.com/v1'`	דריסה של כתובת ה-URL הבסיסית של ה-API.
`language`	`string`	לא	—	דריסת שפה לכל סשן — קוד שפה או הגדרת אזור, כגון `en`, `es` או `fr-FR`. כאשר האפשרות אינה מוגדרת, מוחלת השפה שהוגדרה עבור הסוכן.
`voice`	`string`	לא	—	דריסת קול לכל סשן — שם קול כגון `maria`. כאשר האפשרות אינה מוגדרת, מוחל הקול שהוגדר עבור הסוכן.
`context`	`string`	לא	—	הקשר עובדתי של דף או אתר לכל סשן, שמועבר לסוכן. נחתך בצד השרת ל-12,000 תווים.
`onConnect`	`() => void`	לא	—	נקראת כאשר סשן הקול מתחבר.
`onDisconnect`	`() => void`	לא	—	נקראת כאשר הסשן מסתיים.
`onError`	`(error) => void`	לא	—	נקראת במקרה של שגיאות. לשגיאה יש שדות `error` (קוד) ו-`message`.
`ringtone`	`boolean \| string`	לא	`false`	השמעת צלצול בזמן ההתחברות. `true` עבור צלצול ברירת המחדל, או מחרוזת URL עבור שמע מותאם אישית.

ניקוי

ThunderPhone.mount() מחזירה מופע וידג’ט עם שיטות ניקוי:

<script>
  var widget = ThunderPhone.mount({
    element: '#thunderphone',
    publishableKey: 'pk_live_your_publishable_key',
  })

  // Later, when you want to remove the widget:
  widget.unmount()

  // Or equivalently:
  widget.destroy()
</script>

גם unmount() וגם destroy() מבצעות את אותה פעולה — הן מנתקות כל סשן קולי פעיל ומסירות את הווידג’ט מה-DOM. השתמשו בזו שמתאימה יותר לקריאות הקוד שלכם.

נקו תמיד את הווידג’ט בעת ניווט ביישומים בעלי דף יחיד או כאשר הרכיב המכיל מוסר. כך תבטיחו שסשנים קוליים פעילים מנותקים כראוי.

דוגמאות

ערכת נושא כהה עם צבע מותאם אישית

<div id="thunderphone"></div>

<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
<script>
  ThunderPhone.mount({
    element: '#thunderphone',
    publishableKey: 'pk_live_your_publishable_key',
    theme: 'dark',
    primaryColor: '#8b5cf6',
    title: 'Talk to our AI',
  })
</script>

מיקום מותאם אישית

<div id="thunderphone"></div>

<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
<script>
  ThunderPhone.mount({
    element: '#thunderphone',
    publishableKey: 'pk_live_your_publishable_key',
    position: 'bottom-left',
  })
</script>

עם קריאות חזרה של אירועים

<div id="thunderphone"></div>

<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
<script>
  ThunderPhone.mount({
    element: '#thunderphone',
    publishableKey: 'pk_live_your_publishable_key',
    onConnect: function () {
      console.log('Call started')
    },
    onDisconnect: function () {
      console.log('Call ended')
    },
    onError: function (error) {
      console.error('Widget error:', error.error, error.message)
    },
  })
</script>

עם צלצול

<div id="thunderphone"></div>

<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
<script>
  ThunderPhone.mount({
    element: '#thunderphone',
    publishableKey: 'pk_live_your_publishable_key',
    ringtone: true, // or a custom URL: 'https://example.com/ringtone.mp3'
  })
</script>

שימוש בהפניה לרכיב DOM

<div id="thunderphone"></div>

<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
<script>
  var container = document.getElementById('thunderphone')

  ThunderPhone.mount({
    element: container,
    publishableKey: 'pk_live_your_publishable_key',
  })
</script>

שילוב עם WordPress / CMS

הוסיפו זאת לבלוק HTML מותאם אישית או לכותרת התחתונה של ערכת הנושא שלכם:

<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>

<div id="thunderphone-widget"></div>
<script>
  ThunderPhone.mount({
    element: '#thunderphone-widget',
    publishableKey: 'pk_live_your_publishable_key',
  })
</script>

ניתן למקם את ה-<div> בכל מקום — הוא משמש רק כנקודת העגינה. הווידג’ט עצמו מוצג כשכבת-על קבועה בפינת אזור התצוגה (המוגדרת באמצעות האפשרות position) ואינו זורם עם התוכן שמסביב.

פתרון בעיות

הווידג'ט לא מופיע

ודאו שקובצי ה-CSS וה-JS נטענים. בדקו במסוף הדפדפן שגיאות רשת. ודאו שרכיב היעד קיים ב-DOM לפני הקריאה ל-ThunderPhone.mount().

ThunderPhone אינו מוגדר

הסקריפט עדיין לא נטען. ודאו שתגית ה-<script> עבור widget.js מופיעה לפני קריאת ה-mount שלכם, או עטפו את קריאת ה-mount במאזין DOMContentLoaded.

שגיאה: הדומיין אינו מורשה

הוסיפו את הדומיין שלכם לרשימת הדומיינים המורשים בהגדרות מפתחים ב-app.thunderphone.com. זכרו ש-localhost תמיד מורשה.

השלבים הבאים

עיצוב

התאימו אישית את מראה הווידג’ט באמצעות מאפייני CSS מותאמים אישית.

רכיב React

משתמשים ב-React? שילוב הרכיב פשוט יותר.

​כתובות URL של CDN

​שימוש בסיסי

​אפשרויות טעינה

​ניקוי

​דוגמאות

​ערכת נושא כהה עם צבע מותאם אישית

​מיקום מותאם אישית

​עם קריאות חזרה של אירועים

​עם צלצול

​שימוש בהפניה לרכיב DOM

​שילוב עם WordPress / CMS

​פתרון בעיות

​השלבים הבאים

עיצוב

רכיב React

כתובות URL של CDN

שימוש בסיסי

אפשרויות טעינה

ניקוי

דוגמאות

ערכת נושא כהה עם צבע מותאם אישית

מיקום מותאם אישית

עם קריאות חזרה של אירועים

עם צלצול

שימוש בהפניה לרכיב DOM

שילוב עם WordPress / CMS

פתרון בעיות

השלבים הבאים