Embedding the rules assistant on your site

The Board Game Librarian widget lets you drop a fully functional rules Q&A assistant into any page on your site. Your visitors ask questions about your games; the assistant answers using the official rulebooks. You don't host anything — the widget talks to our servers.

Before you start

A few things need to be in place before writing a single line of code.

An API key. Log into the Partner Portal, open your widget, and go to the General tab. Your API key is listed there. It's a long alphanumeric string — copy it carefully.

Your allowed domains configured. By default, any domain can use your widget (fine for testing, not ideal for production). The General tab has a field for allowed domains. Set this before you go live.

A game in the library. The widget needs at least one game configured. Go to the Games tab in your widget settings to verify your game titles are linked. If a game isn't showing up, contact support — it may need to be added to the catalogue.

No npm packages, no build steps. Nothing server-side.

Method 1: iFrame Embed

The iframe approach is the simplest. You paste one HTML snippet and it works anywhere: plain HTML, WordPress, Webflow, Shopify, Wix, whatever your CMS is.

<iframe
  src="https://www.boardgamelibrarian.ai/embed?apiKey=YOUR_KEY&locale=en"
  width="100%"
  height="700px"
  frameborder="0"
  allow="clipboard-write"
  style="border: none; border-radius: 8px;"
></iframe>

Replace YOUR_KEY with your actual API key. Set the height to whatever fits your layout — 600px to 800px works well for most sidebar or modal designs.

The iframe loads the widget page from our servers directly. All rendering happens inside the frame. Your page doesn't need to do anything except provide space for it.

Limitations of the iframe approach: You can't call JavaScript methods on the widget after it's loaded, and you can't listen for events (like "user asked a question") from the parent page. If you need that kind of interactivity, use Method 2.

Method 2: JavaScript Widget

The JavaScript method gives you more control. One script tag, then a single init() call.

<!-- Add this once, anywhere in your page — ideally before </body> -->
<script src="https://www.boardgamelibrarian.ai/widget.js"></script>

Then initialise the widget:

BGLWidget.init({
  apiKey: 'YOUR_KEY',
  locale: 'en',
  height: '700px',
  transparent: false,
  gameId: 42
});

BGLWidget.init() injects an iframe into the page and manages communication between your page and the widget. You get the same visual result as the direct iframe approach, but you're controlling it via JavaScript — which makes it easier to set options dynamically, change them based on which page the user is on, or integrate with your existing page logic.

The script is small and loads asynchronously. It won't block your page render.

Choosing between the two methods

For most publishers, the iframe is enough.

Use the iframe if:

• You're working in a CMS and don't have easy access to JavaScript execution.
• You just want it working with minimal fuss.
• You don't need to change widget behaviour based on page context.

Use the JavaScript widget if:

• You want to set the gameId dynamically based on which game page the user is viewing.
• You're building a single-page app and need to control when the widget initialises.
• You want consistent init logic across multiple pages.

Both methods produce identical results for the end user. The difference is purely on your side.

Configuration reference

Every parameter available, whether in the iframe URL or the BGLWidget.init() options object:

Visual theming (colours, backgrounds, bubble styles) is managed via Partner Portal → My Themes, not via embed parameters. Create and assign colour palettes to your widget from the Partner Portal. See the Partner Portal guide for details.

Supported locales: en, it, de, fr, es, pt, ru, ja, pl, zh. That's English, Italian, German, French, Spanish, Portuguese, Russian, Japanese, Polish, and Chinese.

The locale setting controls the widget's UI language (button labels, placeholder text, onboarding tooltip). It doesn't lock the Q&A language — the assistant auto-detects the language the visitor types in and responds in kind. A German speaker visiting your English-language site can type in German and get a German answer, regardless of what locale you've set.

Pre-selecting a game

If you're embedding the widget on a dedicated game page, you can pre-select that game so the visitor doesn't have to choose it from the dropdown.

In the iframe URL:

<iframe
  src="https://www.boardgamelibrarian.ai/embed?apiKey=YOUR_KEY&gameId=42"
  width="100%"
  height="700px"
  frameborder="0"
  style="border: none;"
></iframe>

Via JavaScript:

BGLWidget.init({
  apiKey: 'YOUR_KEY',
  gameId: 42
});

The gameId is the numeric ID of the game in the Board Game Librarian catalogue. You'll find it in the Partner Portal under Games — look for the ID column, or check the URL when you view a game's details page.

When gameId is set and the widget only has one game configured, the game selector header is hidden automatically. The widget goes straight to the Q&A input, with less friction for the visitor.

Transparent background

By default, the widget renders with the background colour defined by its active theme. If your site uses a custom background, the widget's solid background can look out of place.

Set transparent=1 (in the URL) or transparent: true (in JS) to remove the widget's background, letting your page show through.

<iframe
  src="https://www.boardgamelibrarian.ai/embed?apiKey=YOUR_KEY&transparent=1"
  width="100%"
  height="700px"
  frameborder="0"
  style="border: none;"
></iframe>

BGLWidget.init({
  apiKey: 'YOUR_KEY',
  transparent: true
});

A few things to keep in mind:

The chat message bubbles and input field still have their own backgrounds — transparent mode removes the widget container background, not every element inside it. Text will remain readable.

If you're using transparent mode on a dark page, make sure your active theme uses light-on-dark colour roles so text stays legible. You can configure this in Partner Portal → My Themes.

Domain restrictions

Your API key can be restricted to specific domains. Any request coming from a domain not on your list gets rejected — the widget loads but won't be able to send questions.

Configure this in the Partner Portal → your widget → General tab → Allowed Domains. Enter a comma-separated list:

yourgamesite.com, shop.yourgamesite.com, yourothersite.com

No protocol prefix needed. The check strips www. automatically, so yourgamesite.com matches both yourgamesite.com and www.yourgamesite.com.

Leave the field empty to allow all domains. Fine for development — lock it down before production.

Why bother? If someone scrapes your API key from your page source and embeds the widget on their own site, they'd consume your rate limit quota. Domain restrictions prevent that.

Testing before you go live

The Partner Portal has a Live Test tab inside each widget's settings. It embeds your actual widget, running with your actual configuration, directly in the portal interface. Use it to verify:

• The correct games are available in the dropdown
• The theme colours look right
• Responses are coming back correctly
• Language detection works (try typing a question in a non-English language)

The Live Test tab runs through the same request pipeline as production. It's not a mock. If something's broken in Live Test, it'll be broken on your site too — and vice versa.

Once Live Test looks good, deploy to your site and do one final check with the actual embedded widget in its real context. Check it on mobile too. The widget is responsive, but your surrounding layout might clip it at smaller breakpoints.

Rate limits and sessions

Your widget has rate limits that control how much it can be used. These are visible in the General tab and are set by the BGL admin team. Three limits apply:

• Per session: maximum questions in a single visitor session
• Per minute: maximum questions across all visitors per minute
• Per day: total daily question budget

Sessions are identified by the visitor's IP address combined with your partner ID. A new session starts when someone visits your page for the first time (or after the session TTL expires). Sessions persist across page reloads within the TTL window, so a visitor who navigates away and comes back continues their conversation.

If a visitor hits the per-session limit, they see a polite message inside the widget and can't ask more questions until the session resets.

If you're expecting high traffic — a Kickstarter launch, a convention, anything unusual — contact support ahead of time. Rate limits can be adjusted.

Troubleshooting

The widget loads but questions fail. Check your allowed domains list. If you're testing from localhost, either add localhost to the allowed domains or leave the list empty during development.

Wrong games showing in the dropdown. Go to the Games tab in your widget settings. The games listed there are the ones the widget serves. If a game is missing, it may not be in the catalogue yet, or it may not be linked to your widget.

The widget looks unstyled or broken. You might have a Content Security Policy (CSP) on your site that's blocking the iframe or the widget.js script. You'll need to add boardgamelibrarian.ai to your CSP's frame-src and script-src directives.

Transparent mode doesn't look right. Check that your active theme's colour roles suit your page background — configure them in Partner Portal → My Themes. Also check that your container element has a background set — if it's transparent all the way up, some browsers render that as white.

Questions are answered in the wrong language. The widget detects language from what the user types, not from the locale parameter. If a visitor types in English, they'll get an English answer. The locale parameter only affects UI strings.

Questions

Can I embed the widget in a modal or popup?

Yes. Put the iframe (or the JS-initialised widget) inside whatever modal container you're using and set a fixed height on the widget container. One thing to watch: if you initialise BGLWidget.init() before the modal is visible, the widget should still work when the modal opens — but test this in your specific setup.

Does the widget work on mobile?

Yes, it's responsive and works on touch devices. Size your iframe's height appropriately — on mobile, 500–600px tends to work better than 700px+.

Can I have multiple widgets on the same page?

Not currently. One widget per page.

Is my API key safe in the page source?

Your API key is visible in your page's HTML source, which is unavoidable for client-side integrations. Domain restrictions (see above) prevent the key from being used on other domains. The key itself only allows Q&A queries — it doesn't grant access to your account or any admin functions.

How do I know how many questions were asked?

The Stats tab in the Partner Portal shows usage data per widget: question counts, response time averages, and language breakdowns.

What happens if BGL is down?

The widget will show an error state. It won't break the rest of your page — it's isolated in an iframe.