Article body
Full article
When a SaaS product adds analytics, the team often sees two extremes: rebuilding a BI platform takes too long, while sending users to an external BI product breaks the experience. Embedded BI PaaS provides a middle path. The ISV retains its product entry point and industry logic, while the platform supplies modeling, metrics, visualization, and AI capabilities.
Embedding is not a single switch. Mature products usually combine three delivery paths: embed a published analytical output, embed an interactive analytical capability, or build a deeper integration through Headless APIs.
Path One: Embed Published Analytics
The team places a published dashboard or report inside a business page, usually with a secure URL, short-lived token, and container. This path ships quickly and works well for customer portals, executive dashboards, and fixed reports. Engineering focuses on single sign-on, tenant context, row-level policy, responsive sizing, and theme consistency.
Output embedding fits stable pages. Users can filter, interact, and export, but the host product has less control over individual components. The ISV should design layout and mobile behavior deliberately instead of shrinking a desktop dashboard into a narrow container.
Path Two: Embed Analytical Capabilities
An SDK can embed charts, filters, designers, or ChatBI modules. The business page controls layout and navigation while users reuse the platform’s analytical capabilities. This path suits industry software that needs self-service analysis, report authoring, or conversational queries.
Modular embedding creates additional frontend and backend integration work. The team must align identity, menu permissions, event communication, and theme variables while managing compatibility between the host application and BI component. A good SDK exposes clear initialization, event, error, and destroy contracts and releases listeners and session resources when a component is removed.
Path Three: Integrate Through Headless APIs
In a Headless design, APIs expose datasets, metrics, queries, charts, and permissions while the ISV builds the interface. It fits products with a strong design system, strict experience requirements, or analytics embedded in a core business workflow. A Data Agent can use the same interfaces to create resources or return structured results.
The freedom comes with more responsibility. API versioning, idempotency, error contracts, audit, and rate limits become part of the product design. The team must also separate synchronous queries from asynchronous jobs and provide progress, cancellation, and execution receipts for long-running work.
Choose by Delivery Boundary
| Dimension | Embedded output | Embedded capability | Headless integration |
|---|---|---|---|
| Delivered object | Published dashboard or report | Chart, designer, ChatBI, or another module | Data and analytics services |
| Frontend effort | Low | Medium | High |
| Product control | Lower | Medium | Highest |
| Delivery time | Short | Medium | Long |
| Best fit | Fixed reports and portals | Self-service analytics and industry apps | Core workflows and custom experiences |
| Main risk | Layout and session behavior | Events and version compatibility | API governance and system complexity |
Do not choose only by development effort. Map the user journey first. Decide who owns each page, which resources can be read or changed, and who handles timeouts and revocation before choosing the integration mode.
All Three Paths Share One Security Contract
Every integration mode needs the same fundamentals:
- The browser receives only a short-lived token scoped to an audience and tenant.
- User, tenant, role, and data scope come from trusted backend context.
- iFrame origins, CORS, and content security policy use explicit allowlists.
- Export, sharing, and write actions have separate authorization and audit.
- Session revocation reaches open components and long-running tasks promptly.
- Error messages do not expose connection strings, internal SQL, or private resource identifiers.
Visual consistency is not identity consistency. A component that looks native to the host product still needs complete server-side authorization.
A Hybrid Plan Is Usually More Practical
Many products use all three paths: embed a dashboard on the operating home page, embed a designer in the analytics center, and call a metric API from a core workflow. A hybrid plan controls cost while keeping high-frequency interactions inside the host application.
Start with published output to validate metrics, permissions, and user demand. Add SDK modules where users truly need self-service analysis. Move only high-value, tightly coupled workflows to Headless APIs. Integration depth should follow business value instead of defaulting to the heaviest architecture.
Further reading: HENGSHI SENSE Product and Technology White Paper.