Reactコンポーネント

ThunderPhone音声ウィジェットをReactアプリケーションに埋め込む

ThunderPhoneWidget コンポーネントは、ミュート、通話終了、接続ステータス表示の組み込みコントロールを備えたガラスモーフィックな通話バーをレンダリングします。React アプリに音声AIを追加する最も迅速な方法です。

インストール

npm install @thunderphone/widget

基本的な使用方法

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
    />
  )
}

Props

コンポーネントは ThunderPhoneWidgetProps を介して以下の props を受け取ります。

Prop	型	必須	デフォルト	説明
`publishableKey`	`string`	はい	--	開発者設定の公開可能 API キー（`pk_live_...`）。エージェントはキーのウィジェット設定から自動的に解決されます。
`theme`	`'light' \| 'dark'`	いいえ	`'light'`	カラースキーム。ウィジェットのルートに `tp--light` または `tp--dark` クラスを適用します。
`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'`	API ベース URL のオーバーライド。
`language`	`string`	いいえ	--	セッションごとの言語オーバーライド。`en`、`es`、`fr-FR` などの言語コードまたはロケールです。未設定の場合、エージェントに設定された言語が適用されます。
`voice`	`string`	いいえ	--	セッションごとの音声オーバーライド。`maria` などの音声名です。未設定の場合、エージェントに設定された音声が適用されます。
`context`	`string`	いいえ	--	エージェントに渡す、セッションごとの事実に基づくページまたはサイトコンテキスト（例: 訪問者が閲覧しているページの詳細）。サーバー側で 12,000 文字に切り詰められます。
`onConnect`	`() => void`	いいえ	--	音声セッションが正常に接続されたときに呼び出されます。
`onDisconnect`	`() => void`	いいえ	--	セッションが終了したときに呼び出されます。
`onError`	`(error) => void`	いいえ	--	エラー発生時に呼び出されます。`error` オブジェクトには `error`（コード）フィールドと `message` フィールドがあります。
`className`	`string`	いいえ	--	ウィジェットコンテナに適用する追加の CSS クラス名。
`ringtone`	`boolean \| string`	いいえ	`false`	接続中に着信音を再生します。デフォルトの着信音には `true`、カスタム音声には URL 文字列を指定します。

例

カスタムカラーを使用したダークテーマ

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      theme="dark"
      primaryColor="#8b5cf6"
      title="Talk to our AI"
    />
  )
}

カスタム位置

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      position="bottom-left"
    />
  )
}

セッションごとの言語、音声、コンテキスト

language、voice、context プロパティは、通話開始時にセッションリクエスト（POST /widget/session）へ渡され、そのセッションにおけるエージェントの設定済みデフォルト値を上書きします。

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function PricingPageWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      language="es"
      voice="maria"
      context="Page: Pricing. Plans: Starter $29/mo, Pro $99/mo. Annual billing saves 20%."
    />
  )
}

context を使用して、訪問者が閲覧中のページ（製品の詳細、価格、ページ固有のよくある質問など）に関する事実情報をエージェントに提供します。サーバー側で12,000文字に切り詰められます。

イベントコールバックを使用

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function SupportWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      onConnect={() => {
        console.log('Voice session connected')
        analytics.track('widget_call_started')
      }}
      onDisconnect={() => {
        console.log('Voice session ended')
        analytics.track('widget_call_ended')
      }}
      onError={(error) => {
        console.error(`Widget error: ${error.error} - ${error.message}`)
      }}
    />
  )
}

カスタムスタイルを使用

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function BrandedWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      primaryColor="#4a90d9"
      className="my-custom-widget"
    />
  )
}

.my-custom-widget .tp-button--end {
  background-color: #e74c3c;
}

利用可能なすべてのCSSクラスとカスタムプロパティについては、スタイリングガイドを参照してください。

着信音を使用

接続の確立中に電話の着信音を再生します。

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function PhoneWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      ringtone={true}
    />
  )
}

音声ファイルのURLを渡してカスタム着信音を使用します。

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  ringtone="https://example.com/my-ringtone.mp3"
/>

ウィジェットがconnecting状態の間は着信音がループし、エージェントが接続するとスムーズにフェードアウトします。

カスタムAPIベースを使用

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  apiBase="https://your-proxy.example.com/v1"
/>

エラー処理

onErrorコールバックが実行されると、次の2つのフィールドを持つエラーオブジェクトを受け取ります。

フィールド	型	説明
`error`	`string`	機械可読なエラーコード
`message`	`string`	人間が読めるエラー説明

一般的なエラーコードには、許可されていないドメイン、エージェントが見つからない、無効なAPIキーなどがあります。

次のステップ

ヘッドレスフック

UIを完全に制御するには、代わりに useThunderPhone フックを使用します。

スタイリング

CSSカスタムプロパティで色、サイズ、レイアウトをカスタマイズします。