Aura Home SDK API

Public customer-side options, methods, and lifecycle events for embedding Aura Home.

Initialization

AuraHome.init({
  container: "#aura-home",
  baseUrl: "https://your-aura-home-runtime.example/",
  sdkHost: "customer.example",
  allowedOrigin: "https://your-aura-home-runtime.example",
  dimensions: {
    width: "100%",
    height: "720px",
    minHeight: "640px"
  }
});

Option	Required	Purpose
`container`	Yes	CSS selector or HTMLElement where the iframe is mounted.
`baseUrl`	Yes	Aura Home runtime URL to open.
`sdkHost`	No	Human-readable host label for telemetry.
`allowedOrigin`	No	Explicit runtime origin for browser messaging.
`sections`	No	Controls visible Aura Home areas.
`theme`	No	Named theme request, mode, CSS variables, and optional stylesheet customization.
`auth`	No	Token callback for enterprise authentication.
`dimensions`	No	Iframe sizing.

Use baseUrl for tenant and environment selection. Do not use tenantId as an isolation, routing, authorization, billing, or data residency boundary.

Sections

sections: {
  chat: true,
  profile: true,
  exploreTools: false,
  navbar: false,
  footer: false,
  onboarding: false,
  pricing: false,
  legalPages: false
}

Theming

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-message-font-size": "15px",
    "--aura-chat-button-font-weight": "700",
    "--aura-card-accent": "#2F6FED",
    "--aura-card-action-background": "#2F6FED",
    "--aura-card-focus-ring": "#8AB4F8"
  },
  stylesheetUrl: "https://customer.example/aura-home-theme.css"
}

The runtime applies theme.id only when the theme is allowed for that runtime. Operators can also publish themes, result-card tokens, and revisioned appearance metadata through the dashboard Appearance Editor. See Appearance and Theming.

Enterprise Authentication

auth: {
  mode: "oidc",
  getToken: async () => {
    return await customerIdentity.getIdToken();
  }
}

Tokens are sent only after the embedded runtime requests one. Do not put tokens in query strings, CSS, local HTML attributes, or logs.

Instance Methods

instance.updateConfig({ sections: { profile: false } });
instance.openChat();
instance.openProfile();
instance.getResolvedAppearance();
instance.hide();
instance.show();
instance.destroy();

Resolved Appearance

The SDK exposes the resolved, non-secret appearance contract after the runtime applies tenant defaults, requested theme values, and dashboard-published settings.

const appearance = instance.getResolvedAppearance();

instance.on("appearanceResolved", (event) => {
  console.log(event.payload?.resolvedThemeId);
  console.log(event.payload?.features?.resultCardsEnabled);
  console.log(event.payload?.themeRevision);
});

Field	Purpose
`resolvedThemeId`	The visual profile actually applied by the runtime.
`features.resultCardsEnabled`	Whether enriched result-card rendering is active for the current runtime.
`rendererCatalog`	Public renderer metadata the host can use for support and diagnostics.
`cardTokens`	Resolved card accent, action, surface, and focus-ring tokens.
`themeRevision`	Published appearance revision information for audit and support.

Lifecycle Events

Event	Meaning
`loaded`	The iframe load event fired.
`ready`	The embedded runtime announced readiness.
`appearanceResolved`	The runtime resolved non-secret appearance metadata such as result-card feature state, renderer catalog, card tokens, and active theme revision.
`configAck`	The runtime accepted SDK configuration.
`tokenProvided`	The SDK sent an auth token to the runtime.
`profileOpened`	`openProfile()` was called.
`chatOpened`	`openChat()` was called.
`error`	The runtime reported an error.
`destroyed`	The SDK instance was destroyed.