リファレンス

このページは、バージョン 0.1.0 の動作に基づいています。script タグで読み込んだ場合、関数はグローバルオブジェクト AskAIButton にあります（例：AskAIButton.init()）。npm の場合は、同じ名前の関数を import します。

init() のオプション

すべて省略できます。使えない値（型が違う、範囲外など）は無視され、既定値が使われます。

例

AskAIButton.init({
  position: 'bottom-left',
  accentColor: '#27455c',
  providers: ['chatgpt', 'claude'],
  defaultProvider: 'claude',
  presets: {
    ja: ['料金を教えてください', '納期はどのくらいですか？'],
    en: ['How much does it cost?', 'How long does delivery take?'],
  },
  siteUrl: 'https://example.com/shop/',
  onSend: (event) => {
    console.log(event.provider, event.source, event.url);
  },
});

data-* 属性

data-askai を付けた script タグでは、次の属性でオプションを指定できます。値はすべて文字列で書きます。

maxUrlLength、queryTemplate、labels、onSend、AIサービスの定義、言語別の presets には、対応する属性がありません。これらを使うときは init() を呼んでください。

関数

// 自分のボタンからパネルを開く
document.querySelector('#ask').addEventListener('click', () => AskAIButton.open());

// 標準の文面を調べる
console.log(AskAIButton.defaults('ja').labels.queryTemplate);

イベント

document に、次の CustomEvent を送ります。

質問の本文は、イベントにも onSend にも渡しません。 ボタン自体は、これらの情報をどこにも送りません。アクセス解析に記録するかどうかは、サイト側で決めてください。

document.addEventListener('askai:send', (event) => {
  const { provider, source, url } = event.detail;
  // 例：自分のサイトの計測に記録する
});

クエリテンプレート

AIに渡す文面は、テンプレートの変数を置き換えて作ります。標準のテンプレートは言語ごとに決まっています。

{question}

この質問について、以下のURLを参照して回答してください。
{site_url}

これ以外の {...} は、そのまま残ります。標準のテンプレートが使うのは {question} と {site_url} だけです。表示中のページや Markdown 版を渡したい場合は、テンプレートを書き換えます。

AskAIButton.init({
  queryTemplate: {
    ja: '{question}\n\n次のページを参照して回答してください。\n{url}',
    en: '{question}\n\nPlease refer to this page to answer.\n{url}',
  },
});

文面は URL エンコードして、AIサービスのURLテンプレートの {query} に入れます。できあがったURLが maxUrlLength を超えると、送信できません。

AIサービスの定義

標準では、次の3つが登録されています。

これらのURLの形式は、各サービスが公式に公開しているものではなく、予告なく変わることがあります。どの項目も、設定で置き換えられます（「しくみと注意点」）。

定義の項目は次のとおりです。

既存のAIサービスの一部を変える

providers に、id と変えたい項目だけを書きます。

AskAIButton.init({
  providers: [
    'chatgpt',
    { id: 'claude', method: 'copy_and_open' },
    { id: 'googleai', color: '#333' },
  ],
});

AIサービスを追加する

registerProvider() で登録すると、providers で id を指定できるようになります。providers を省略した場合は、登録済みのすべてが登録順に表示されます。

AskAIButton.registerProvider({
  id: 'example',
  name: { ja: 'Example AI', en: 'Example AI' },
  urlTemplate: 'https://ai.example.com/search?q={query}',
  color: '#444',
});

AskAIButton.init({
  providers: ['chatgpt', 'claude', 'googleai', 'example'],
  labels: { 'note.example': '質問は自動で送信されます。' },
});

ai.example.com は説明用の架空のアドレスです。実際に追加するときは、そのサービスが質問をURLで受け取れるかどうかを確認してください。

文言

labels で、ボタンとパネルの文言を上書きできます。キーは次のとおりです。

{provider} は、選択中のAIサービスの名称に置き換わります。note.<id> は、そのAIサービスを選んだときに note の後ろに続けて表示する注記です。

全言語共通で指定することも、言語別に指定することもできます。

AskAIButton.init({
  labels: {
    // すべての言語で使う
    placeholder: '例：送料はいくらですか？',
    // 言語別
    ja: { buttonLabel: 'AIに聞いてみる' },
    en: { buttonLabel: 'Ask an AI' },
  },
});

言語

UIの言語は、閲覧者のブラウザーの設定ではなく、ページの言語に合わせます。次の順で決まります。

1. lang オプション（'auto' 以外が指定されている場合）
2. <html lang>
3. ブラウザーの言語（navigator.language）
4. 英語

pt-BR のような地域付きの言語は、pt-BR、pt の順に辞書を探し、なければ英語で表示します。同梱している辞書は日本語（ja）と英語（en）です。

言語別に書いた presets、queryTemplate、AIサービスの name は、ページの言語、その基本の言語、en の順に探します。言語別の labels は、ページの言語に一致するものを使い、UIが英語で表示されるときは en の指定も使います。

言語によって、AIに渡すURLは変わりません。{site_url} は、言語ごとに /en/ のようなフォルダーに分けているサイトでも、どの言語のページでもオリジン（https://example.com/）です。言語ごとのトップページを渡したい場合は、その言語のページで data-site-url（init() では siteUrl）を指定します。例：data-site-url="https://example.com/en/"。

言語を追加する

registerLocale() に、言語コードと文言を渡します。指定しなかったキーは英語で表示されます。

AskAIButton.registerLocale('fr', {
  buttonLabel: "Demander à l'IA",
  panelTitle: "Interroger l'IA sur ce site",
  placeholder: 'Saisissez votre question',
  send: 'Demander à {provider} ↗',
  close: 'Fermer',
  queryTemplate: "{question}\n\nVeuillez vous référer à l'URL suivante pour répondre à cette question.\n{site_url}",
});

AskAIButton.init();

CSS カスタムプロパティ

ボタンとパネルは Shadow DOM の中にあるため、ページのCSSの影響を受けません。見た目のうち、次のものはCSSカスタムプロパティで変えられます。:root などに指定してください。

:root {
  --askai-accent: #27455c;
  --askai-panel-width: 400px;
}

accentColor、offset、zIndex オプションを指定した場合は、オプションの値が優先されます。

ページごとに非表示にする

次の meta タグがあるページでは、init() を呼んでもボタンを表示しません。共通のテンプレートで読み込んでいて、一部のページだけ外したいときに使います。

<meta name="askai" content="off">

SPA での動作

• ページのURLとタイトルは、送信のたびにその時点のものを読み取ります。画面遷移のたびに init() を呼び直す必要はありません。
• 画面ごとに質問の例などを変えたいときは、update() を使います。パネルが開いていても、入力中の質問は消えません。
• <meta name="askai" content="off"> を確認するのは、init()、update()、registerProvider()、registerLocale() を呼んだときです。meta タグの変化は監視しません。
• ボタンは document.body の直下に追加されます。不要になったら destroy() で取り除きます。

対応ブラウザー

配布ファイルは ES2019 の構文で出力しています。Chrome、Edge、Firefox、Safari の最新2バージョンと、iOS の Safari、Android の Chrome を対象にしています。

Content Security Policy

• スタイルは、構築済みスタイルシート（adoptedStyleSheets）で Shadow DOM に適用します。現在のブラウザーでは <style> 要素を使わないため、style-src に 'unsafe-inline' を追加する必要はありません。構築済みスタイルシートに対応していないブラウザーでは、Shadow DOM の中に <style> 要素を作ります。
• script-src では、askai-button.min.js を置いた場所を許可してください。CDN から読み込む場合は、CDN のホスト（https://cdn.jsdelivr.net または https://unpkg.com）です。data-askai を使えば、インラインスクリプトは不要です。
• ボタンは外部と通信しないため、connect-src の設定は不要です。