Reference

This page describes version 0.1.0. When the file is loaded with a script tag, the functions are on the global object AskAIButton (for example AskAIButton.init()). With npm, you import functions of the same names.

Options of init()

Every option can be left out. A value that cannot be used (wrong type, out of range and so on) is ignored and the default applies.

Example

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

On a script tag with data-askai, these attributes set the options. All values are written as text.

There is no attribute for maxUrlLength, queryTemplate, labels, onSend, definitions of AI services, or presets per language. Call init() to use those.

Functions

// Open the panel from a button of your own
document.querySelector('#ask').addEventListener('click', () => AskAIButton.open());

// Look up the built-in text
console.log(AskAIButton.defaults('en').labels.queryTemplate);

Events

These events (each a CustomEvent) are dispatched on document.

The question itself is never passed, neither to the events nor to onSend. The button sends this information nowhere. Whether to record it in your analytics is your decision.

document.addEventListener('askai:send', (event) => {
  const { provider, source, url } = event.detail;
  // for example: record it in the statistics of your own site
});

Query template

The text handed to the AI is made by replacing the variables of a template. Each language has its own built-in template.

{question}

Please refer to the following URL to answer this question.
{site_url}

Any other {...} is left as it is. The built-in templates use {question} and {site_url} only. To hand over the current page or its Markdown version, write your own template.

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

The text is URL-encoded and put into the place of {query} in the URL template of the AI service. If the resulting address is longer than maxUrlLength, it cannot be sent.

Definitions of AI services

Three services are registered from the start.

These URL formats are not documented by the services and can change without notice. Every field can be replaced through the settings (see "How it works and caveats").

A definition has these fields:

Changing part of a built-in service

In providers, write the id and only the fields you want to change.

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

Adding an AI service

A service registered with registerProvider() can be named by its id in providers. When providers is left out, all registered services are shown in the order they were registered.

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': 'Your question is sent automatically.' },
});

ai.example.com is a made-up address for this explanation. Before adding a real service, check whether it accepts a question in its URL.

Wording

labels replaces the wording of the button and the panel. These are the keys:

{provider} is replaced by the name of the selected AI service. note.<id> is a remark shown after note while that service is selected.

Wording can be given for all languages at once, or per language.

AskAIButton.init({
  labels: {
    // used in every language
    placeholder: 'e.g. How much is shipping?',
    // per language
    ja: { buttonLabel: 'AIに聞いてみる' },
    en: { buttonLabel: 'Ask an AI' },
  },
});

Language

The language of the UI follows the page, not the settings of the visitor's browser. It is decided in this order:

1. the lang option, when it is set to something other than 'auto'
2. <html lang>
3. the language of the browser (navigator.language)
4. English

For a language with a region, such as pt-BR, a dictionary is looked for under pt-BR, then pt; without one the UI is in English. The built-in dictionaries are Japanese (ja) and English (en).

presets, queryTemplate and the name of an AI service, when written per language, are looked up under the language of the page, then its base language, then en. Per-language labels are used when they match the language of the page; when the UI is shown in English, those under en are used as well.

The language does not change the address that is handed to the AI. {site_url} is the origin of the page (https://example.com/) on pages of every language, also when each language lives in a folder such as /en/. To hand over the top page of each language instead, set data-site-url (siteUrl in init()) on the pages of that language, for example data-site-url="https://example.com/en/".

Adding a language

Pass a language code and the wording to registerLocale(). Keys you leave out are shown in English.

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

The button and the panel live in a shadow DOM, so the CSS of the page does not affect them. These parts of their look can be changed with CSS custom properties. Set them on :root, for example.

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

When the options accentColor, offset or zIndex are given, the options win.

Hiding the button on a page

A page with this meta tag does not show the button, even when init() is called. Use it when the script is loaded from a shared template and some pages should be left out.

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

Single-page applications

• The address and the title of the page are read at the moment of sending. There is no need to call init() again after a navigation.
• To change the example questions or other options from one view to the next, use update(). The question being typed is kept, also while the panel is open.
• <meta name="askai" content="off"> is checked when init(), update(), registerProvider() or registerLocale() is called. Changes of the meta tag are not watched.
• The button is added directly under document.body. Remove it with destroy() when it is no longer needed.

Browser support

The distributed files use ES2019 syntax. The targets are the last two versions of Chrome, Edge, Firefox and Safari, plus Safari on iOS and Chrome on Android.

Content Security Policy

• The styles are applied to the shadow DOM with a constructed stylesheet (adoptedStyleSheets). Current browsers need no <style> element for this, so 'unsafe-inline' does not have to be added to style-src. In a browser without constructed stylesheets, a <style> element is created inside the shadow DOM.
• In script-src, allow the place where askai-button.min.js is served from. For a file loaded from a CDN this is the host of the CDN (https://cdn.jsdelivr.net or https://unpkg.com). With data-askai, no inline script is needed.
• The button makes no network requests, so nothing has to be set in connect-src.