Your first 5 minutes: adding the rules assistant to your site

Last updated: April 5, 2026

What you will have in 5 minutes

A small floating button in the corner of your website. When a visitor clicks it, a chat panel slides open with a rules assistant that can answer questions about the board games you configure. The visitor types a question, gets an answer with citations to the rulebook, and goes back to browsing your site. No signup, no app install, no friction.

This guide gets you from zero to a working embed in about 5 minutes. For theming, analytics, domain restrictions, and advanced configuration, see the full widget integration guide linked at the end.

Step 1 — Request an API key

The widget is gated by an API key tied to your partner account. If you do not yet have an account, contact us through the partner portal signup page. An existing partner can generate new API keys from the partner dashboard under Widgets → Create Widget.

Each API key is scoped to:

  • A specific partner account
  • A specific set of games you have configured
  • Optional domain restrictions (so the key only works on your own sites)

Keep the key in your environment config, not in version control. Although the key is designed to be safe to expose in client-side code, treating it as a secret is still good practice.

Step 2 — Copy the embed snippet

The simplest integration is one script tag. Drop this at the bottom of your HTML template, just before the closing </body> tag:

<script
  src="https://boardgamelibrarian.ai/widget.js"
  data-api-key="YOUR_API_KEY_HERE"
  data-widget-id="1"
  async>
</script>

Replace YOUR_API_KEY_HERE with the key from Step 1. The data-widget-id identifies which of your widget configurations to load — if you only have one, it will be 1.

That is the whole snippet. No build step, no npm install, no framework requirements.

Step 3 — Paste it into your site

Where exactly you put the snippet depends on your stack:

  • Static HTML: paste it inside the <body> tag of each page where you want the widget. Usually right before </body>.
  • WordPress: use a "Header and Footer" plugin and paste the snippet into the Footer section. It will load on every page automatically.
  • Next.js / React: add it to your root layout via next/script with strategy="afterInteractive". Do not wrap it in a component that gets re-mounted — the widget is a singleton.
  • Shopify / Squarespace / Wix: use the platform's "custom code injection" feature and paste into the footer slot.

The widget attaches itself to document.body on load. It does not require any container element on your page.

Step 4 — Test locally

Open your site in a browser. You should see a small circular button fixed to the lower-right corner of the viewport. Click it. The chat panel should slide in.

Type a question about one of your configured games, for example: "How does combat work?" You should get an answer within 5-10 seconds, with clickable PDF citations underneath.

If the widget does not appear:

  1. Open the browser console (F12) and look for errors.
  2. Verify the data-api-key value is correct.
  3. Verify your domain is not blocked by the key's domain restrictions.
  4. Confirm the script tag is inside <body>, not <head>.

If the chat panel opens but returns an error when you ask a question, the most likely cause is that no games are configured on the widget yet — that is Step 5.

Step 5 — Configure your games

Go to the partner portal at boardgamelibrarian.ai/partners, find your widget under Widgets, and open it. The Games tab shows which games are available in this widget's dropdown. Add at least one.

For each game you add, you can:

  • Upload a rulebook PDF directly (if not already in our library)
  • Set a display name
  • Mark the game as the default (opens first when the widget loads)
  • Restrict the widget to a single game (hides the game selector entirely — useful for single-game product pages)

Once games are configured, the widget is fully operational. Visitors can ask questions and get rulebook-grounded answers.

What players can ask

Real questions I handle well:

  • "How many action points do I get per turn?"
  • "Can I attack a unit in my own zone of control?"
  • "What happens when I draw a card while my hand is full?"
  • "How do I win?"
  • "Walk me through my first turn step by step"

Questions I handle poorly or not at all:

  • Questions about specific card text when no card reference PDF is loaded
  • Questions about rules that exist only in diagrams I cannot read
  • Questions about strategy ("what is the best opening move?") — I answer rules, not tactics

What happens behind the scenes

When a visitor sends a question, the widget forwards it to the orchestrator service, which detects the language, runs vector search against the rulebook chunks for the selected game, assembles the top matching passages into a context window, and calls a large language model to synthesise the answer with citations. Most answers arrive in 5-7 seconds. For ambiguous or contested rules, the system automatically escalates to a deeper search that also pulls in relevant community discussion — this takes 7-35 seconds and produces a more thorough answer.

Next steps

The snippet above is the simplest possible integration. For production use, you will probably want at least:

  • Custom theming — colours, fonts, transparent mode, dark mode
  • Domain restrictions — lock the API key to your specific domains
  • Analytics — question volume, confidence scores, player feedback, top questions
  • Iframe or React component — alternative embed formats for tighter integration
  • Language lock — force the widget into a specific language regardless of browser locale

All of these are covered in the full Widget Integration Guide. Start there once the quick start is working.

FAQ

Does the widget work on mobile? Yes. It collapses to a bottom drawer on narrow viewports.

Will it slow down my site? The widget.js loader is under 20 KB and loads async. The chat UI only loads when a visitor clicks the button. There is effectively zero performance cost on initial page load.

Can I style the widget to match my brand? Yes. The partner portal has a theme editor with live preview. You can customise 17 colour variables (background, text, buttons, links, bot bubbles, borders, etc.) and save multiple themes per partner account.

Does it work without JavaScript? No. The widget is a JavaScript chat interface — progressive enhancement is not possible here.

Can visitors see each other's questions? No. Every session is isolated. Sessions are keyed to the visitor's IP plus the partner account, so a visitor returning later gets conversation continuity, but no visitor can see another visitor's history.

Is there a cost per question? Costs depend on your partner plan. Unlimited tiers are available for publishers with high-traffic product pages. Check the partner billing tab for your current plan and usage.