CDN / スクリプトタグ

CDN ビルドには React が内部的にバンドルされているため、静的サイト、WordPress、Webflow、または HTML を追加できる任意のページでウィジェットを使用できます。npm、バンドラー、フレームワークは不要です。

CDN URL

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

latest URL は、ダッシュボードの埋め込みスニペットジェネレーターが生成する URL です。5 分間キャッシュされ、新しい安定版リリースが自動的に反映されます。固定された /widget/vX.Y.Z/ パスは不変で長期間キャッシュされます。固定する場合は、開発対象の @thunderphone/widget npm リリースとバージョンを一致させてください。

基本的な使用方法

<!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'` (light) / `'#ffffff'` (dark)	アクセントカラーとして使用する 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`（コード）フィールドと `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 ファイルの両方が読み込まれていることを確認してください。ブラウザコンソールでネットワークエラーを確認してください。ThunderPhone.mount() を呼び出す前に、対象の要素が DOM 内に存在することを確認してください。

ThunderPhone が定義されていない

スクリプトがまだ読み込まれていません。widget.js 用の <script> タグがマウント呼び出しより前にあることを確認するか、マウント呼び出しを DOMContentLoaded リスナーでラップしてください。

ドメインが許可されていないエラー

app.thunderphone.com の 開発者 設定にある許可済みドメインリストへドメインを追加してください。localhost は常に許可されていることに注意してください。

次のステップ

スタイリング

CSS カスタムプロパティでウィジェットの外観をカスタマイズします。

React コンポーネント

React を使用していますか？コンポーネント統合のほうが簡単です。

​CDN URL

​基本的な使用方法

​マウントオプション

​クリーンアップ

​例

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

​カスタム位置

​イベントコールバック付き

​着信音付き

​DOM 要素参照を使用する

​WordPress / CMS 統合

​トラブルシューティング

​次のステップ

スタイリング

React コンポーネント

CDN URL

基本的な使用方法

マウントオプション

クリーンアップ

例

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

カスタム位置

イベントコールバック付き

着信音付き

DOM 要素参照を使用する

WordPress / CMS 統合

トラブルシューティング

次のステップ