Tutorial

Embed Aura Home in a customer site

This tutorial walks through a simple white-label integration that keeps the customer website in control of layout while Aura Home owns the assistant runtime.

1. Prepare the Page Slot

Create a stable container where the assistant should appear.

<section class="assistant-panel">
  <div id="aura-home"></div>
</section>

2. Initialize a Transparent Embed

Start with chat and profile only. This keeps the customer page in control of navigation, footer, pricing, and legal surfaces.

const aura = AuraHome.init({
  container: "#aura-home",
  baseUrl: "https://your-aura-home-runtime.example/",
  sections: {
    chat: true,
    profile: true,
    navbar: false,
    footer: false,
    exploreTools: false,
    onboarding: false,
    pricing: false,
    legalPages: false
  }
});

3. Apply Brand Styling

Ask the runtime for an approved theme and use CSS variables for safe brand-level changes. Use a hosted stylesheet only when broader refinements are required.

aura.updateConfig({
  theme: {
    id: "cadisa",
    mode: "dark",
    cssVariables: {
      "--color-brand-primary": "#2F6FED",
      "--color-brand-primary-hover": "#1F56C6",
      "--color-brand-accent": "#8AB4F8",
      "--aura-chat-header-background": "#0b1f4d",
      "--aura-chat-title-font-family": "'Montserrat', system-ui, sans-serif",
      "--aura-card-accent": "#2F6FED",
      "--aura-card-action-background": "#2F6FED",
      "--aura-card-focus-ring": "#8AB4F8"
    }
  }
});

4. Connect Enterprise Identity

Use a callback so tokens are requested only when needed and are never placed in query strings.

AuraHome.init({
  container: "#aura-home",
  baseUrl: "https://your-aura-home-runtime.example/",
  auth: {
    mode: "oidc",
    getToken: async () => customerIdentity.getIdToken()
  }
});

5. Coordinate Lifecycle

Listen for readiness before removing host-side loading states, and inspect resolved appearance metadata when support needs to confirm the active theme revision.

const unsubscribe = aura.on("ready", () => {
  document.body.classList.add("aura-home-ready");
});

const unsubscribeAppearance = aura.on("appearanceResolved", (event) => {
  console.log(event.payload?.themeRevision);
});

// Later, when the host no longer needs the embed:
unsubscribe();
unsubscribeAppearance();
aura.destroy();

6. Launch Checklist

• Verify the runtime URL opens in a browser tab.
• Confirm the customer origin is allowed by the runtime configuration.
• Confirm the requested theme.id is allowed or publish the visual profile in the dashboard Appearance Editor.
• Confirm appearanceResolved reports the expected result-card state and themeRevision.
• Confirm the token callback returns a valid OIDC/JWT token when enterprise auth is enabled.
• Test desktop and mobile container heights.
• Confirm no secrets appear in URLs, CSS variables, HTML attributes, or logs.