CDN / znacznik skryptu

Kompilacja CDN wewnętrznie zawiera React, więc możesz używać widżetu w witrynach statycznych, WordPressie, Webflow lub na dowolnej stronie, na której możesz dodać kod HTML. Nie wymaga npm, bundlera ani frameworka.

Adresy 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>

Adresy URL latest są generowane przez generator fragmentów osadzania w panelu. Są buforowane przez 5 minut i automatycznie uwzględniają nowe stabilne wersje. Przypięte ścieżki /widget/vX.Y.Z/ są niezmienne i buforowane długoterminowo — jeśli przypinasz wersję, dopasuj ją do wydania npm @thunderphone/widget, względem którego tworzysz aplikację.

Podstawowe użycie

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

Widżet jest montowany w elemencie docelowym i renderowany jako pasek o stałej pozycji w rogu obszaru widoku (domyślnie bottom-right, sterowane opcją position). Element montowania jest jedynie korzeniem React — jego położenie na stronie nie wpływa na miejsce wyświetlania widżetu.

Opcje montowania

ThunderPhone.mount() przyjmuje te same opcje co komponent React oraz właściwość element:

Opcja	Typ	Wymagana	Domyślnie	Opis
`element`	`string \| HTMLElement`	Tak	—	Selektor CSS (np. `'#thunderphone'`) lub referencja do elementu DOM.
`publishableKey`	`string`	Tak	—	Publiczny klucz API (`pk_live_...`). Agent jest automatycznie określany na podstawie konfiguracji widżetu klucza.
`theme`	`'light' \| 'dark'`	Nie	`'light'`	Schemat kolorów.
`primaryColor`	`string`	Nie	`'#000000'` (jasny) / `'#ffffff'` (ciemny)	Ciąg koloru CSS używany jako kolor akcentu.
`title`	`string`	Nie	`'Voice assistant'`	Tekst wyświetlany na pasku widżetu.
`position`	`'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'`	Nie	`'bottom-right'`	Stała pozycja w obszarze widoku.
`apiBase`	`string`	Nie	`'https://api.thunderphone.com/v1'`	Zastąpienie podstawowego adresu URL API.
`language`	`string`	Nie	—	Zastąpienie języka dla sesji — kod języka lub ustawienia regionalne, takie jak `en`, `es` lub `fr-FR`. Gdy nie jest ustawione, stosowany jest skonfigurowany język agenta.
`voice`	`string`	Nie	—	Zastąpienie głosu dla sesji — nazwa głosu, taka jak `maria`. Gdy nie jest ustawione, stosowany jest skonfigurowany głos agenta.
`context`	`string`	Nie	—	Faktyczny kontekst strony lub witryny dla sesji przekazywany agentowi. Po stronie serwera skracany do 12 000 znaków.
`onConnect`	`() => void`	Nie	—	Wywoływane po połączeniu sesji głosowej.
`onDisconnect`	`() => void`	Nie	—	Wywoływane po zakończeniu sesji.
`onError`	`(error) => void`	Nie	—	Wywoływane w przypadku błędów. Błąd zawiera pola `error` (kod) i `message`.
`ringtone`	`boolean \| string`	Nie	`false`	Odtwarzaj dzwonek podczas łączenia. `true` dla domyślnego dzwonka lub ciąg URL dla własnego dźwięku.

Czyszczenie

ThunderPhone.mount() zwraca instancję widżetu z metodami czyszczenia:

<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>

Zarówno unmount(), jak i destroy() wykonują to samo — rozłączają aktywną sesję głosową i usuwają widżet z DOM. Użyj metody, która lepiej pasuje do Twojego kodu.

Zawsze czyść widżet podczas przechodzenia do innej strony w aplikacjach jednostronicowych lub gdy element zawierający widżet jest usuwany. Zapewnia to prawidłowe rozłączenie aktywnych sesji głosowych.

Przykłady

Ciemny motyw z niestandardowym kolorem

<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>

Niestandardowa pozycja

<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>

Z wywołaniami zwrotnymi zdarzeń

<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>

Z dzwonkiem

<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>

Użycie referencji do elementu 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>

Integracja z WordPress / CMS

Dodaj to do bloku niestandardowego HTML lub stopki motywu:

<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>

Element <div> można umieścić w dowolnym miejscu — służy wyłącznie jako punkt montowania. Sam widżet jest renderowany jako stała nakładka w rogu obszaru widoku (ustawianym za pomocą opcji position) i nie jest układany wraz z otaczającą treścią.

Rozwiązywanie problemów

Widżet się nie wyświetla

Upewnij się, że wczytano zarówno pliki CSS, jak i JS. Sprawdź konsolę przeglądarki pod kątem błędów sieciowych. Zweryfikuj, czy element docelowy istnieje w DOM przed wywołaniem ThunderPhone.mount().

ThunderPhone nie jest zdefiniowany

Skrypt nie został jeszcze wczytany. Upewnij się, że tag <script> dla widget.js znajduje się przed wywołaniem montowania, lub umieść wywołanie montowania w detektorze DOMContentLoaded.

Błąd niedozwolonej domeny

Dodaj swoją domenę do listy dozwolonych domen w ustawieniach Deweloperzy na stronie app.thunderphone.com. Pamiętaj, że localhost jest zawsze dozwolony.

Widget

Adresy URL CDN

Podstawowe użycie

Opcje montowania

Czyszczenie

Przykłady

Ciemny motyw z niestandardowym kolorem

Niestandardowa pozycja

Z wywołaniami zwrotnymi zdarzeń

Z dzwonkiem

Użycie referencji do elementu DOM

Integracja z WordPress / CMS

Rozwiązywanie problemów

Kolejne kroki

Stylizacja

Komponent React

​Adresy URL CDN

​Podstawowe użycie

​Opcje montowania

​Czyszczenie

​Przykłady

​Ciemny motyw z niestandardowym kolorem

​Niestandardowa pozycja

​Z wywołaniami zwrotnymi zdarzeń

​Z dzwonkiem

​Użycie referencji do elementu DOM

​Integracja z WordPress / CMS

​Rozwiązywanie problemów

​Kolejne kroki

Stylizacja

Komponent React

Adresy URL CDN

Podstawowe użycie

Opcje montowania

Czyszczenie

Przykłady

Ciemny motyw z niestandardowym kolorem

Niestandardowa pozycja

Z wywołaniami zwrotnymi zdarzeń

Z dzwonkiem

Użycie referencji do elementu DOM

Integracja z WordPress / CMS

Rozwiązywanie problemów

Kolejne kroki