Help Center

Widget 埋め込みガイド

チャットウィジェットをあなたのサイトに組み込む手順をフレームワーク別に解説します。

ヘルプセンターに戻る

始める前に

コンソールの Bot 設定 → Widget タブ から以下の 2 つを取得してください。

  • 1Bot ID（bot_ で始まる公開ID）
  • 2Widget トークン（knotic_wgt_ で始まる値 — 発行時のみ表示）

また、許可オリジン設定にウィジェットを設置するドメインを追加することで、不正なサイトからの呼び出しを防げます。

1

基本実装（HTML）

HTML ファイルの </body> 直前に貼り付けるだけで動作します。フレームワーク不要のシンプルな方法です。

html
<!-- knotic Widget -->
<script
  src="https://knotic.make-it-tech.com/widget.js"
  data-bot-id="YOUR_BOT_ID"
  data-widget-token="YOUR_WIDGET_TOKEN"
  defer
></script>
2

Next.js（App Router）

推奨配置: app/layout.tsx の最上位 RootLayout に置くのがベストです。 全ページに1度だけ読み込まれ、SPA ナビゲーション時も再マウントされません。 特定ページのみに表示したい場合はコンポーネント化してください。

① layout.tsx に直接（全ページ共通）

tsx
// app/layout.tsx（推奨）
import Script from "next/script"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ja">
      <body>
        {children}

        {/* ページ全体に1回だけ読み込む */}
        <Script
          src="https://knotic.make-it-tech.com/widget.js"
          data-bot-id="YOUR_BOT_ID"
          data-widget-token="YOUR_WIDGET_TOKEN"
          strategy="lazyOnload"
        />
      </body>
    </html>
  )
}

② コンポーネント化（特定ページのみ）

tsx
// components/knotic-widget.tsx（特定ページのみに表示したい場合）
"use client"

import Script from "next/script"

export function KnoticWidget() {
  return (
    <Script
      src="https://knotic.make-it-tech.com/widget.js"
      data-bot-id="YOUR_BOT_ID"
      data-widget-token="YOUR_WIDGET_TOKEN"
      strategy="lazyOnload"
    />
  )
}

// 使いたいページで:
// import { KnoticWidget } from "@/components/knotic-widget"
// <KnoticWidget />
3

React（Vite / Create React App）

推奨配置: src/App.tsx または src/main.tsx でカスタムフックとして定義するか、public/index.html の body 末尾に直接記述する方法が最もシンプルです。

① カスタムフック（動的挿入）

tsx
// src/App.tsx または src/main.tsx（Vite / CRA）
import { useEffect } from "react"

function useKnoticWidget() {
  useEffect(() => {
    const script = document.createElement("script")
    script.src = "https://knotic.make-it-tech.com/widget.js"
    script.setAttribute("data-bot-id", "YOUR_BOT_ID")
    script.setAttribute("data-widget-token", "YOUR_WIDGET_TOKEN")
    script.defer = true
    document.body.appendChild(script)

    return () => {
      // クリーンアップ（SPA でページ離脱時にウィジェットを削除）
      document.body.removeChild(script)
    }
  }, [])
}

export default function App() {
  useKnoticWidget()
  return <div>{/* ... */}</div>
}

② public/index.html に直接記述（最もシンプル）

html
<!-- public/index.html（シンプルに body 末尾へ追加する場合）-->
<body>
  <div id="root"></div>

  <script
    src="https://knotic.make-it-tech.com/widget.js"
    data-bot-id="YOUR_BOT_ID"
    data-widget-token="YOUR_WIDGET_TOKEN"
    defer
  ></script>
</body>
4

Vue.js（Vue 3 / Nuxt）

推奨配置: src/App.vue の onMounted で挿入するのが一般的です。 Nuxt を使っている場合は nuxt.config.ts の app.head.script に追加する方法が最もクリーンです。

vue
<!-- src/App.vue -->
<script setup lang="ts">
import { onMounted, onUnmounted } from "vue"

let scriptEl: HTMLScriptElement | null = null

onMounted(() => {
  scriptEl = document.createElement("script")
  scriptEl.src = "https://knotic.make-it-tech.com/widget.js"
  scriptEl.setAttribute("data-bot-id", "YOUR_BOT_ID")
  scriptEl.setAttribute("data-widget-token", "YOUR_WIDGET_TOKEN")
  scriptEl.defer = true
  document.body.appendChild(scriptEl)
})

onUnmounted(() => {
  if (scriptEl) document.body.removeChild(scriptEl)
})
</script>

<template>
  <!-- アプリ本体 -->
</template>
5

WordPress

推奨配置: 子テーマの functions.php に wp_footer フックで追加するのがベストプラクティスです。 テーマ編集が難しい場合は「外観 → ウィジェット」または「外観 → カスタマイズ → 追加CSS/HTML」からカスタム HTML ブロックとして追加できます。

php
<?php
// functions.php に追加（テーマのカスタマイズ推奨）
function knotic_widget_script() {
    echo '<script
        src="https://knotic.make-it-tech.com/widget.js"
        data-bot-id="YOUR_BOT_ID"
        data-widget-token="YOUR_WIDGET_TOKEN"
        defer
    ></script>';
}
add_action( 'wp_footer', 'knotic_widget_script' );
6

data 属性オプション一覧

ボタン位置・表示モードはコンソールのWidget設定から変更できます。 scriptタグには data-bot-id と data-widget-token の2つのみ記述すれば動作します。data-mode / data-position は省略した場合にコンソールの設定値が自動的に使用されます。 同一Botを複数サイトに設置してサイトごとに見た目を変えたい場合などに任意で追加してください。

html
<!-- 必須属性のみで動作します -->
<script
  src="https://knotic.make-it-tech.com/widget.js"
  data-bot-id="bot_xxxxxxxxxx"       <!-- 必須: Bot の公開ID -->
  data-widget-token="knotic_wgt_xx"  <!-- 必須: Widgetトークン -->
></script>

<!-- コンソール設定を上書きしたい場合のみ追加 -->
<script
  src="https://knotic.make-it-tech.com/widget.js"
  data-bot-id="bot_xxxxxxxxxx"
  data-widget-token="knotic_wgt_xx"
  data-mode="overlay"                <!-- 任意: コンソール設定を上書き / overlay / redirect / both -->
  data-position="right-bottom"       <!-- 任意: コンソール設定を上書き / right-bottom / right-top -->
></script>
属性必須値説明
data-bot-id✓bot_xxxBot の公開ID
data-widget-token✓knotic_wgt_xxxWidgetトークン
data-modeoverlay / redirect / both表示モードの上書き（省略時はコンソール設定値を使用）
data-positionright-bottom / right-topボタン位置の上書き（省略時はコンソール設定値を使用）
参考・対処

トラブルシューティング

Widget が表示されない・動作しない場合は、まずブラウザの開発者ツール（F12）→「Console」タブでエラーメッセージを確認してください。

origin not allowed

原因: 設置先のドメインが許可オリジンに未登録

対処: コンソール → Bot設定 → Widgetタブ →「許可オリジン」に設置先URL（例: https://example.com）を追加して保存

invalid widget token

原因: Widgetトークンが無効または再発行後の古いトークンを使用中

対処: コンソールのWidgetトークン管理で「トークン再発行」し、新しいトークンでscriptタグを更新

widget is disabled

原因: コンソールでWidgetが無効化されている

対処: コンソール → Bot設定 → Widgetタブで「Widgetを有効にする」をオンにして保存

bot is not ready

原因: ソースのインデックス処理が未完了

対処: コンソールのソース一覧でインデックス状態を確認。処理中の場合は完了後に再試行

bot is not public

原因: Botの公開設定がオフになっている

対処: コンソール → Bot設定 → 基本タブで「公開する」をオンにして保存

bot is force-stopped

原因: Botが運営側により停止中

対処: サポートにお問い合わせください

それでも解決しない場合：開発者ツール →「Network」タブで /api/widget/config へのリクエストを確認してください。 レスポンスの error フィールドに詳細が含まれています。

セキュリティについて

Widgetトークン（knotic_wgt_）はHTMLソースに公開されます。これは意図的な設計ですが、以下の仕組みで保護されています。

許可オリジンによるCORS制御

/api/widget/config はリクエスト元のOriginヘッダーを検証します。 コンソールの「許可オリジン」に登録されていないドメインからのリクエストは 403 を返します。 トークンが漏洩しても、登録外のドメインからは利用できません。

トークン即時無効化

トークンが漏洩した恐れがある場合は、コンソールのWidgetトークン管理から「トークン再発行」を実行してください。 旧トークンは即時無効化されます。新しいトークンでscriptタグを更新すれば復旧できます。

ハッシュ保存

Widgetトークンはデータベースにハッシュ値のみ保存されています。平文のトークンはコンソールでの発行時に1度だけ表示されます。

注意：フロントエンドのコードに SUPABASE_SERVICE_ROLE_KEY や STRIPE_SECRET_KEY などのサーバー専用シークレットを含めないでください。 Widgetトークンのみをフロントエンドに公開する設計としてください。

CSP（Content Security Policy）対応

サイトにContent Security Policyを設定している場合、以下のディレクティブを追加してください。

http
# 必要なCSPディレクティブ
Content-Security-Policy:
  script-src  'self' https://knotic.make-it-tech.com;
  connect-src 'self' https://knotic.make-it-tech.com;
  frame-src   'self' https://knotic.make-it-tech.com;
  img-src     'self' https://knotic.make-it-tech.com data:;
script-src

widget.js スクリプト本体の読み込みを許可

connect-src

/api/widget/config・/api/v1/chat など API通信を許可

frame-src

チャット画面をiframeで表示する場合に必要

img-src

チャット内の画像・アイコン表示を許可（data: はBot設定のロゴ等で使用）

Next.js での設定例（next.config.ts）

ts
// next.config.ts
const cspHeader = [
  `script-src 'self' https://knotic.make-it-tech.com`,
  `connect-src 'self' https://knotic.make-it-tech.com`,
  `frame-src 'self' https://knotic.make-it-tech.com`,
  `img-src 'self' https://knotic.make-it-tech.com data:`,
].join("; ")

export default {
  async headers() {
    return [{ source: "/(.*)", headers: [{ key: "Content-Security-Policy", value: cspHeader }] }]
  },
}

注意：unsafe-inline や unsafe-eval の追加は不要です。 既存のCSPポリシーがある場合は、上記のホストのみを追記してください。

不明な点はコンソールからお問い合わせください。
コンソールへ