@assembly-js/app-bridge

Helper functions for postMessage communications between custom apps (embedded in iframes) and the Copilot parent application.

Installation

npm/yarn

npm install @assembly-js/app-bridge
# or
yarn add @assembly-js/app-bridge

CDN (Script Tag)

<script src="https://cdn.copilot.com/app-bridge/latest.js"></script>

Or with a specific version (content-hashed for caching):

<script src="https://cdn.copilot.com/app-bridge/assembly-bridge.ab3f8e2d.min.js"></script>

Usage

CDN Usage

When loaded via script tag, the library exposes a global AssemblyBridge object:

<script src="https://cdn.copilot.com/app-bridge/latest.js"></script>
<script>
  // Set breadcrumbs
  AssemblyBridge.header.setBreadcrumbs([
    { label: "Home" },
    { label: "Settings", onClick: () => console.log("clicked") },
  ]);

  // Set a primary CTA button
  AssemblyBridge.header.setPrimaryCta({
    label: "Save",
    icon: "Check",
    onClick: () => saveData(),
  });

  // Navigate to a different route
  AssemblyBridge.navigate("settings");
</script>

npm Usage

import { AssemblyBridge } from "@assembly-js/app-bridge";

// Set breadcrumbs
AssemblyBridge.header.setBreadcrumbs([
  { label: "Dashboard" },
  { label: "Users", onClick: () => console.log("navigated") },
]);

// Set actions menu
AssemblyBridge.header.setActionsMenu([
  { label: "Download", icon: "Download", onClick: () => downloadFile() },
  {
    label: "Delete",
    icon: "Trash",
    color: "red",
    onClick: () => confirmDelete(),
  },
]);

API Reference

AssemblyBridge.header

setBreadcrumbs(items)

Set the breadcrumb navigation items in the header.

AssemblyBridge.header.setBreadcrumbs([
  { label: "Home" },
  { label: "Projects", onClick: () => navigateToProjects() },
  { label: "Current Project" },
]);

Parameters:

• items: Array of { label: string, onClick?: () => void }

setPrimaryCta(config)

Set or clear the primary CTA button.

// Set a CTA
AssemblyBridge.header.setPrimaryCta({
  label: "Save Changes",
  icon: "Check",
  onClick: () => save(),
});

// Clear the CTA
AssemblyBridge.header.setPrimaryCta(null);

Parameters:

• config: { label: string, icon?: Icon, onClick: () => void } or null

setSecondaryCta(config)

Set or clear the secondary CTA button. Same API as setPrimaryCta.

setActionsMenu(items)

Set the actions dropdown menu items.

AssemblyBridge.header.setActionsMenu([
  { label: "Archive", icon: "Archive", onClick: () => archive() },
  { label: "Delete", icon: "Trash", color: "red", onClick: () => remove() },
]);

Parameters:

• items: Array of { label: string, icon?: Icon, color?: 'red', onClick: () => void }

AssemblyBridge.configure(config)

Configure the bridge with additional settings.

AssemblyBridge.configure({
  additionalOrigins: ["portal.yourcompany.com", "https://custom-domain.com"],
  debug: true, // Enable debug logging
});

Parameters:

• config.additionalOrigins: Array of origins to allow for postMessage communication. Origins without a protocol default to HTTPS. Can be called multiple times - origins are cumulative.
• config.debug: Enable debug mode to log warnings to the console when messages cannot be sent (e.g., parent origin not in allowlist, not running in an iframe). Useful for troubleshooting.

Note: The bridge includes built-in support for *.copilot.app, *.myassembly.com, dashboard.assembly.com, localhost, and their staging equivalents. You only need to use configure() for custom portal domains.

AssemblyBridge.navigate(route, options?)

Navigate to a different route in the parent application.

// Navigate to settings
AssemblyBridge.navigate("settings");

// Navigate to a specific app
AssemblyBridge.navigate("apps", { id: "app-123" });

// Navigate to a specific form
AssemblyBridge.navigate("forms", { id: "form-456" });

Parameters:

• route: One of the supported routes (see below)
• options: Optional { id?: string }

Supported Values

Icons

Available for CTAs: Archive, Plus, Templates, Trash, Check

Available for action menu items: Archive, Plus, Templates, Trash, Download, Check, Disconnect

Routes

• apps - Applications page (supports id for specific app)
• billing - Billing page
• contracts - Contracts page
• files - Files page (supports id for channel)
• forms - Forms page (supports id for specific form)
• helpdesk - Help desk page (supports id for specific article)
• invoices - Invoices page
• messages - Messages page (supports id for channel)
• notifications - Notifications page (supports id for channel)
• settings - Settings page
• settings.billing - Billing settings
• settings.profile - Profile settings
• products.create - Create product page
• products.edit - Edit product page (supports id for product)

TypeScript Support

The package includes TypeScript declarations. Import types as needed:

import type {
  BreadcrumbItem,
  CtaConfig,
  ActionMenuItem,
  Route,
  Icon,
} from "@assembly-js/app-bridge";

Development

# Install dependencies
yarn install

# Build
yarn build

# Type check
yarn type-check

# Run tests
yarn test

# Generate content-hashed files
yarn generate-manifest

License

MIT