Advice Embed

Taffrail offers two ways to embed advice into a website or application:

Both render identical advice. The Web Component uses Shadow DOM for style isolation and exposes events you can subscribe to. The iframe embed is a single HTML snippet that works anywhere.

Web Component (recommended)

The <taffrail-component> custom element renders advice directly in your page using Shadow DOM — no iframe required. It handles auto-height and style isolation, and it works in React, Vue, Angular, and other SPA frameworks.

📘

Alias: <taffrail-advice> is an alias for <taffrail-component>. Both tag names behave identically.

Quick start

Add the component element and registration script to your page:

<taffrail-component data-id="YOUR_ADVICE_SET_ID"></taffrail-component>

<script type="module">
  import { default as registerTaffrail } from "https://YOUR_HOST/dist/js/embed.wc.bundle.js";

  const embedContext = registerTaffrail({
    apiBaseUrl: "https://YOUR_HOST",
    tokenProvider: {
      getToken: async () => {
        return { Authorization: "Bearer YOUR_API_KEY" };
      }
    }
  });
</script>

Replace the placeholders:

• YOUR_HOST — your Taffrail subdomain, e.g., acme.advice.taffrail.com (production) or acme.staging-advice.taffrail.com (staging)
• YOUR_API_KEY — your API key provided by Taffrail
• YOUR_ADVICE_SET_ID — the Advice Set ID (e.g., TFhToq34...)

Attributes

Script setup: registerTaffrail

registerTaffrail() initializes the Web Component system and returns an event context you can use to subscribe to component events.

import { default as registerTaffrail } from "https://YOUR_HOST/dist/js/embed.wc.bundle.js";

const embedContext = registerTaffrail({
  apiBaseUrl,   // Required — base URL for API calls (your Compass host)
  tokenProvider // Required — object with a getToken method
});

tokenProvider

The tokenProvider must have a getToken method that returns an object of HTTP headers to include with API requests. Typically this is an Authorization header with a Bearer token.

const tokenProvider = {
  getToken: async () => {
    // Return authorization headers
    return { Authorization: "Bearer YOUR_API_KEY" };
  }
};

getToken is invoked before every API request, so you can put token-refresh logic inside it.

Events

Use the embedContext returned by registerTaffrail() to listen for events from any Taffrail component on the page:

embedContext.addEventListener("taffrail", (e) => {
  const { event, payload } = e.detail;
  console.log("Event:", event, "Payload:", payload);
});

Event payload shape

{
  event: "state-change",    // event name
  payload: {
    componentId: "TF...",   // the advice set ID
    instanceId: "TF...-1",  // unique instance identifier
    state: { ... },         // current variable state
    onload: true            // true on initial load
  }
}

Events

Dynamic updates

Switching the Advice Set

Update data-id to load a different Advice Set in the same component instance:

const widget = document.querySelector("taffrail-component");
widget.setAttribute("data-id", "TFnewAdviceSetId");

Updating Variables in place

Update the config attribute to change input values:

const widget = document.querySelector("taffrail-component");
widget.setAttribute("config", JSON.stringify({
  state: {
    Tax_Filing_Status: "married filing joint",
    Tax_Year: "2026"
  }
}));

What you get

• Shadow DOM isolation — component styles do not leak into or out of your page
• Auto-height — the component resizes itself; no iframe-resizer required
• SPA-friendly — drop into React, Vue, Angular, or plain HTML
• Dynamic updates — change data-id or config at any time
• Event-driven — subscribe to state-change and navigation events

Helpers

The embedContext returned by registerTaffrail() exposes a few helpers:

// Get all taffrail component elements on the page
const elements = embedContext.getElements();

IFrame embed

The iframe embed is a single HTML snippet, similar in shape to Google Maps or YouTube embeds, that loads Taffrail advice into an iframe on your page.

Quick start

Paste this snippet into your site, app, or CMS:

<div class="taffrail-embed"><div class="taffrail-rw"><a data-tr-url data-tr-key="YOUR_API_KEY"  href="https://www.advice.taffrail.com/c/TFU3nYztaJ8yxgNGQkGsP7k/iframe?"></a></div></div><script src="https://www.advice.taffrail.com/dist/js/embed.bundle.js" async charset="utf-8"></script>

Hello World example

oEmbed

You can also fetch embed code dynamically through the oEmbed API. View the oEmbed response for the Hello World example.

Configuration

Behavior

• The widget's width is set by the parent container on your page.
• The widget resizes its height to match the rendered advice, including when a user changes an assumption.
• Branding and presentation are configured with Taffrail at integration time.

Passing Variables

Both integration methods accept Variable name/value pairs that pre-fill inputs and assumptions. This is the usual way to render a fully-answered piece of advice on first paint.

Web Component

Pass variables via the config attribute as a JSON string. Variables go inside a state object:

<taffrail-component
  data-id="YOUR_ADVICE_SET_ID"
  config='{"state": {"Tax_Filing_Status": "married filing joint", "Tax_Year": "2026"}}'>
</taffrail-component>

Top-level keys in config (outside state) configure the component itself. Keys under state are passed to the API as Variable values.

IFrame embed

Append Variable name/value pairs as query parameters on the embed URL:

?Tax_Filing_Status=married+filing+joint&Tax_Year=2026

Next steps

Once the Hello World example is working, get the embed codes for your own Advice Sets from the AdviceBuilder dashboard or from Taffrail directly.

• Advice Content Types — what advice can be embedded and how it's formatted
• Parameters — the full list of Variables you can pre-set
• API Reference — direct programmatic access