10.6.3.1. スクリプト開発モデル「アシスタント実行 UI」実装¶
このドキュメントでは、スクリプト開発モデルで「アシスタント実行 UI」を埋め込む方法について解説します。
目次
10.6.3.1.1. 基本的な使い方¶
10.6.3.1.1.1. ステップ1: HTMLの準備¶
まず、プレゼンテーションページ（HTML）に以下の要素を追加します：
<imart type="head">
<meta http-equiv="X-Intramart-Secure-Token" content='<imart type="imSecureToken" mode="value" />' />
<script src="im_copilot/js/extension.bundle.js"></script>
</imart>
<div id="assistant-area"></div>
<script>
// アシスタントUIを登録
window.imCopilot.register({
targetElementId: 'assistant-container',
assistantId: 'your-assistant-id',
threadId: 'unique-thread-id',
inputPlaceholder: 'メッセージを入力してください'
});
</script>
要素追加時のポイントは、以下の通りです：
- <head> タグにセキュアトークン情報（imSecureToken）を追加
- スクリプト im_copilot/js/extension.bundle.js を追加
- アシスタントUIを表示するDIV要素（ID）を追加
- JavaScript 関数（imCopilot.register）を用いて、DIV要素の中に「アシスタント実行 UI」を埋め込む処理を追加
10.6.3.1.1.2. ステップ2: パラメータの設定¶
window.imCopilot.register() メソッドには以下のパラメータを指定できます：
| パラメータ名 | 必須 | 説明 |
|---|---|---|
| targetElementId | ○ | アシスタントUIを表示するDIV要素のID |
| assistantId | ○ | 使用するアシスタントのID |
| threadId | × | 会話履歴を識別するための一意のID |
| inputPlaceholder | × | 入力欄に表示するプレースホルダーテキスト（デフォルト: “プロンプトを入力”） |
10.6.3.1.2. 実装例¶
10.6.3.1.2.1. シンプルな実装例¶
最もシンプルな実装例を示します。
プレゼンテーションページ（sample_basic.html）:
<imart type="head">
<title>アシスタント実行サンプル - 基本実装</title>
<meta http-equiv="X-Intramart-Secure-Token" content='<imart type="imSecureToken" mode="value" />' />
<script src="im_copilot/js/extension.bundle.js"></script>
</imart>
<div id="assistant-area"></div>
<script>
// アシスタントUIを登録
window.imCopilot.register({
targetElementId: "assistant-area",
assistantId: "sample-rag-assistant",
threadId: 'thread_' + new Date().getTime(),
inputPlaceholder: "Input prompt"
});
</script>
10.6.3.1.2.2. 動的にスレッドIDを生成する例¶
ユーザごとに異なるスレッドIDを生成する実装例です。
ファンクション・コンテナ（sample_dynamic.js）:
var threadId;
function init(request) {
// アシスタントID
let assistantId = "sample-rag-assistant";
// アカウントコンテキスト取得
let accountContexts = Contexts.getAccountContext();
// ユーザコードを取得
let userCd = accountContexts.userCd;
// タイムスタンプを生成
let timestamp = new Date().getTime();
// スレッドIDを生成
threadId = 'thread_' + userCd + '_' + assistantId + '_' + timestamp;
}
プレゼンテーションページ（sample_dynamic.html）:
<imart type="head">
<title>アシスタント実行サンプル - 動的制御</title>
<meta http-equiv="X-Intramart-Secure-Token" content='<imart type="imSecureToken" mode="value" />' />
<script src="im_copilot/js/extension.bundle.js"></script>
</imart>
<div id="assistant-area"></div>
<script>
// アシスタントUIを登録
window.imCopilot.register({
targetElementId: "assistant-area",
assistantId: "sample-rag-assistant",
threadId: '<imart type="string" value=threadId />',
inputPlaceholder: "Input prompt"
});
</script>
10.6.3.1.3. 注意事項¶
- extension.bundle.jsの読み込み位置
- extension.bundle.jsは必ず<head>タグ内で読み込んでください
- body内で読み込むと、正常に動作しない可能性があります
- スレッドIDの管理
- threadIdは会話履歴を識別するために使用されます
- 同じthreadIdを使用すると、以前の会話履歴が引き継がれます
- 新しい会話を開始したい場合は、新しいthreadIdを生成してください
- セキュリティトークンの設定
- meta要素でX-Intramart-Secure-Tokenを必ず設定してください
- これがないとAPIへのアクセスが拒否されます
10.6.3.1.4. トラブルシューティング¶
10.6.3.1.4.1. アシスタントが表示されない場合¶
以下の点を確認してください：
- extension.bundle.jsの読み込み位置
- <head>タグ内で読み込まれているか確認
- bodyタグ内での読み込みではないか
- セキュリティトークンの設定
- <meta http-equiv="X-Intramart-Secure-Token"> が設定されているか
- <imart type="imSecureToken" mode="value" /> の記述が正しいか
- HTML要素の存在確認
- targetElementIdで指定したID属性を持つ要素が存在するか
- DOMContentLoadedイベント発生後に実行されているか
- アシスタントID
- assistantIdが正しいか
- アシスタントへのアクセス権限があるか
10.6.3.1.4.2. エラーメッセージの対処¶
| エラーメッセージ | 対処法 |
|---|---|
| “Error: Failed to find extension parent element” | 指定したtargetElementIdの要素が存在することを確認 |
| “Error: Assistant configuration error. Check definition and authorization settings.” | アシスタントIDが正しいか、アシスタントが存在するか、アシスタントへのアクセス権限があるか確認 |
| “TypeError: Cannot read properties of undefined” | extension.bundle.jsが<head>タグ内で読み込まれているか確認 |
| “TypeError: Cannot read properties of null” | セキュリティトークンが正しく設定されているか確認 |
10.6.3.1.5. まとめ¶
スクリプト開発での「アシスタント実行 UI」の埋め込みは、わずか数行のコードで実現できます。
この機能を活用することで、独自のWebアプリケーションにAIアシスタント機能を簡単に統合できます。