Advice Embed

Taffrail provides two ways to embed advice into your website or application:

Both methods render the same Taffrail advice experience. The Web Component uses Shadow DOM for style isolation and provides richer event handling, while the IFrame embed is a drop-in snippet that works anywhere.

Web Component (Recommended)

The <taffrail-component> custom element renders advice directly in your page using Shadow DOM — no iframe needed. It handles auto-height, style isolation, and works seamlessly in SPAs (React, Vue, etc.).

📘

Alias: <taffrail-advice> is an equivalent alias for <taffrail-component>. Both tag names work 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)

The registerTaffrail() function initializes the Web Component system and returns an event context for managing 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" };
  }
};

If your token expires, getToken is called before each API request, so you can implement token refresh logic here.

Events

After calling registerTaffrail(), use the returned embedContext to listen for events dispatched by all Taffrail components on the page:

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

Event Detail 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
  }
}

Key Events

Dynamic Updates

Changing 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

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"
  }
}));

Key Features

• Shadow DOM isolation — component styles don't leak into or out of your page
• Auto-height — the component adjusts height automatically, no iframe-resizer needed
• SPA-friendly — works in React, Vue, Angular, and other frameworks
• Dynamic updates — change data-id or config attributes at any time
• Event-driven — rich event system for state changes and navigation

Helpers

The embedContext object returned by registerTaffrail() also provides:

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

IFrame Embed

The IFrame embed creates an iframe-based widget using a simple HTML snippet. This works similarly to embeds for Google Maps, YouTube videos, and other oEmbed-compatible content.

Quick Start

Paste this embed code into your website, 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

Fetching embed code dynamically is also possible using the oEmbed API. Using the Hello World example, view the oEmbed API. This is only an example.

Configuration

Key Features

• You determine the widget's width by placing it inside an element on your site.
• The widget will automatically adjust its height based on the Advice shown and continue to resize based on assumptions modified by users.
• Work with Taffrail to customize the presentation, branding, and more.

Passing Variables

Both integration methods support passing Variable name/value pairs to pre-fill inputs and assumptions. This is commonly used to render complete Advice with all inputs answered or predefined.

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 the config JSON (outside of state) are treated as component configuration, while keys inside state are sent to the API as variable values.

IFrame Embed

Append variable name/value pairs as query parameters to the embed URL:

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

Next Steps

After testing with the Hello World example, you can find unique embed codes for given Advice Sets from your dashboard or Taffrail directly.

• Learn about Advice Content Types to understand what types of advice can be embedded
• See the full list of Variables available for configuration
• Explore the API Reference for programmatic access