Analyze with AI
Get AI-powered insights from this Mad Devs article:
A logistics SaaS receives a customer request: show whether deliveries arrive on time, identify late orders, and let users open the delivery record from the report. This illustrative scenario gives the team a concrete way to evaluate SaaS embedded analytics.
Embedded analytics puts analytical views inside an application so customers can explore their own operational data within the product. Choosing an integration approach requires agreement on the calculation, accessible records, and user journey. This guide follows one report from source records through reconciliation and an embedding decision. You will be able to define a first release, test candidate approaches, and assign ownership before expanding access.
Key takeaways
- Start with a customer question and the action that follows the answer. This defines the useful boundary of the first report.
- Give the metric card, detail table, and export one shared definition, including tenant scope, exclusions, and refresh context.
- Choose an embedding approach by testing the same report against access, navigation, and maintenance requirements.
- Expand the release after customer scenarios pass acceptance. A working pilot establishes readiness for that scope; continued observation guides the next investment.
Define the first customer reporting task
Specify the question, audience, and next action
For customer A, the question is: “What share of our delivered orders arrived on time during the selected period, and which orders were late?” After reviewing the answer, the user opens a delivery record in the main product to investigate it.
Translate that question into five requirements: one on-time delivery metric, a period filter, an outcomes table, CSV export for an authorized role, and navigation to the delivery record. Label the example permissions “product viewer” and “export-enabled user.” These labels describe required behavior within the existing permission system.
Specify the table columns with the customer: delivery identifier, planned deadline, actual delivery time, and outcome. Confirm that the identifier resolves to the record users already recognize. Ask a customer representative to walk from the report to that record; this exposes navigation requirements before implementation.
Set the first release boundary
Release a standard report first. A custom report builder, AI chat, editing product data from BI, and scheduled email delivery each require a separate scope decision.
Specific data rules, product navigation, or integration constraints can create custom development work. A ready-made embed may also satisfy the entire reporting task. Evaluate it against the agreed requirements before allocating work to new components.
Mad Devs’ GuardRails case study documents a delivered customer-facing reporting dashboard and API, scan and report history, and later interface improvements based on updated requirements. This historical example illustrates the development scope behind a reporting feature: data access, an interface, and iterations. The logistics report below is an independent illustration.
Establish the data and metric contract
Agree on grain, period, and exclusions
Define the example metric as on-time delivery rate among eligible completed deliveries. Its grain is one unique delivery within a tenant. The definition is specific to this report; customers may use different operational KPIs.
A delivery qualifies when its status is delivered and both its planned deadline and actual delivery timestamp are known. Select the reporting period using delivered_at. A qualifying delivery is on time when delivered_at is earlier than or equal to planned_deadline.
Cancelled and unfinished deliveries stay outside the denominator. Completed deliveries with a missing deadline become data-quality exclusions. Show their count for the same tenant and reporting period beside the eligible-delivery denominator so users can see the calculation's coverage. An identical record received twice represents one delivery.
Write these rules into the report specification, including the unique key and the definition version. Have the product owner confirm the meaning and the data owner confirm that source fields support it. This is the point to resolve whether a delivery identifier represents a shipment, an order, or another entity in the existing product.
Keep every report surface on the same definition
The metric card, detail table, and CSV must share tenant scope, period, status rules, definition version, and refresh context. A card aggregates deliveries; the eligible-delivery export lists those deliveries individually. Reconcile their membership and calculation together.
Record the definition in the selected data model or reporting layer and check that each surface uses it. The metric-modeling guidance in this implementation article, updated October 7, 2026, also recommends shared definitions across analytical surfaces.
All timestamps in this example use UTC. For the live product, agree on the customer's calendar, timezone conversion, corrections, and freshness display separately. A corrected deadline or a later data refresh can change the answer. Preserve enough context to explain which version and snapshot produced a result.
Reconcile the delivery report against source records
Calculate the result for one customer
Illustrative dataset with invented records.
These nine input rows form a snapshot at calculation time. Uniqueness is defined by tenant_id plus delivery_id. The repeated A2 row is an identical record received again; its status is delivered in both rows. The table labels the repeat for readability. This example contains no conflicting updates or revised promised deadlines.
Every time below falls on October 5, 2026, in UTC. The selected reporting period includes that day. A dash indicates an absent delivery timestamp.
| Tenant | Delivery | Status | Planned deadline | Delivered at |
|---|---|---|---|---|
| A | A1 | Delivered | 14:00 | 13:50 |
| A | A2 | Delivered | 14:00 | 14:20 |
| A | A2 | Delivered – identical duplicate | 14:00 | 14:20 |
| A | A3 | Delivered | 16:00 | 15:40 |
| A | A4 | Cancelled | 14:00 | – |
| A | A5 | In transit | 17:00 | – |
| A | A6 | Delivered | Missing | 13:45 |
| B | B1 | Delivered | 14:00 | 14:10 |
| B | B2 | Delivered | 16:00 | 15:30 |
Customer A has six unique deliveries after deduplication. A1, A2, and A3 are eligible. A1 and A3 meet their deadlines; A2 arrives late. The on-time delivery rate is therefore 2/3 = 66.7%, rounded to one decimal place.
A6 is completed but lacks a deadline, producing one data-quality exclusion. A4 and A5 have excluded statuses. B1 and B2 belong to customer B and remain outside A's report.
Counting the duplicate A2 would produce four eligible rows with two on-time outcomes: 2/4 = 50%. The discrepancy comes from counting a received record twice at the chosen grain. Use this deliberate error to check the calculation during implementation.
Trace the number into details and export
Clicking the late count should show A2 once. The CSV available to an export-enabled user should contain the eligible set A1/A2/A3. Recalculating from those rows should reproduce 66.7%. Show A6 in a separate data-quality message, with its missing deadline visible; assigning it an on-time or late outcome would invent information.
Hold the filters and as-of context constant while comparing these surfaces. If a refresh occurs between opening the card and downloading the CSV, capture a matching snapshot or rerun the comparison against the same refresh. A later answer can legitimately change as source records change.
Keep this dataset as a regression fixture for each candidate implementation, with explicit expected outcomes. It proves the example's arithmetic and membership rules. Production acceptance will also need representative customer data, including the correction patterns excluded from this simplified snapshot.
Choose the integration approach against the same report
Compare hosted embeds, components, and a custom interface
Use the reconciled report to compare integration boundaries. Each route must reproduce the metric, authorized delivery set, export behavior, and navigation.
| Approach | What to test on this report | Product team work |
|---|---|---|
| Authenticated hosted embed / iframe | Customer scope, period filter, details, export rights, and navigation into the product | Data model, session and access setup, report configuration, integration, and acceptance |
| Vendor SDK / embedded components | Available components, supported events and navigation, theming, and frontend compatibility | Integration code, component lifecycle, data and access configuration, and updates |
| Custom UI over an API / semantic layer | API coverage for the metric and details, query limits, and maintainability | UI, API integration, loading and failure states, tests, and maintenance of the selected layer |
An SDK or custom interface can use an existing analytics service. Choosing these routes determines which components and behavior your team owns. It does not require creating an entire BI engine.
For each candidate, record the configuration tested and any requirement that needs additional code. Include licensing and permitted embedding use in the evaluation so the accepted configuration can be used in production.
Test the capability before committing to custom work
For this illustrative scenario, begin by testing an authenticated hosted embed. Load customer A's report, select the period, open the late details, download the permitted CSV, and navigate to A2. Repeat with a user whose export permission is absent.
Capabilities depend on the particular embedding mode and authentication configuration. For example, Metabase v65's embedding introduction, checked November 13, 2026, distinguishes modular embedding from full-app embedding and treats authentication as a separate choice. Its comparison shows that authentication affects available interactions. Verify the exact combination needed for your report.
Select an approach that passes the requirements with acceptable constraints and maintenance obligations. If a candidate embed cannot support required navigation or the access contract, test its component or API route. Record the blocking behavior so the additional development scope has a concrete justification.
Define the integration work and operational ownership
Draw the request path from the authenticated application user to the reporting layer and source data. Mark where the metric is defined, where trusted customer context is established, and which component enforces each restriction. The application's backend should derive tenant and role context from authenticated state. An editable browser filter cannot establish permission.
Apply tenant-scoped authorization to the aggregate, details, export, and delivery record. Test direct requests as well as visible controls. Export permission may differ from viewing permission. If reporting access depends on a feature entitlement, include that rule in the same end-to-end verification.
Define the behavior and application time for tenant switching, logout, and access changes. Check whether an existing analytics session or cached view remains usable after each event. A link from the report passes a delivery identifier; the main product independently checks access before opening that record.
Name owners for changes and failures
Assign a product owner for metric definitions and a data owner for pipelines and source-field changes. Name owners for report configuration, application integration, and customer support. One person may cover several areas, provided each responsibility is explicit.
Agree on stale, empty, and error states. An empty eligible set needs a clear “no eligible deliveries” state with no percentage calculation. A failed refresh needs an explicit data status, the last successful refresh time when available, and an agreed response.
Plan how schema changes and SDK updates reach testing, who responds to a broken report, and how the feature can be disabled for the pilot group. Define a fallback customer-support path when reporting is unavailable.
A platform provider may operate the analytics infrastructure while the product team owns data, configuration, and customer rules. Check these boundaries against the selected service's documented responsibilities and support arrangements before accepting operational ownership.
Accept the first release and resolve the example
Validate correctness, access, and behavior
Turn the report specification into actions with observable results. Use the invented fixture for deterministic reconciliation, then repeat relevant checks with representative customer records in an authorized test environment.
| Check | Action and expected result |
|---|---|
| Control dataset | Open A's report for the example period. It shows 66.7%, three eligible deliveries, and a separate warning about A6. |
| Details and CSV | Open late details: A2 appears once. Export as an authorized user: the eligible CSV contains A1/A2/A3 with matching filters and as-of context. |
| Access | Request B1/B2 as A's user: access is rejected. Request an export directly as a user without export rights: no export is returned. |
| Context and freshness | Switch tenants and log out: the agreed session behavior applies. Simulate a refresh failure: the data state is explicit. |
| Workload and user journey | Test large accounts and agreed concurrency within the project's performance budget. Navigate from late count to A2 and open the authorized delivery record. |
Set performance budgets before testing: data volume, concurrent sessions, acceptable response time, and environment. Include both reporting behavior and its effect on the existing product. The small arithmetic fixture cannot establish capacity for a large customer account.
Capture the tested configuration, results, and unresolved defects. A failed access check blocks the release. A failed workload test requires remediation or an explicitly narrower scope that is tested again. Ask a customer representative to complete the reporting task without guidance; record where the journey stops.
Close the scenario with a concrete release decision
In this illustrative outcome, the team confirms during its pilot evaluation that the chosen authenticated embed supports the required period filter, details, role-appropriate CSV, and authorized product navigation. It releases the standard report to a limited customer group after the acceptance checks pass.
The ready-made BI component remains part of the solution. The product team owns the calculation, tenant and access configuration, navigation, and regression tests. The custom report builder stays outside this release until customer demand for creating reports is confirmed.
If acceptance reveals a blocking capability, revisit the implementation approach before widening access. Retain the metric contract and fixture when testing the replacement route, so the reporting task stays stable through that decision.
This outcome is an illustrative release specification, with no claim that this pilot was conducted. After a real launch, observe whether customers complete the reporting task, the number and cause of correctness incidents, support requests, and measured performance against the agreed budget. Those observations inform expansion; the pilot alone establishes no retention or financial return.
Conclusion
The illustrative logistics SaaS team chooses an authenticated embed after verifying that it can deliver the agreed report and product journey. Your next step is to choose one customer question, agree on its metric and data contract, and test a candidate against the product's actual constraints.
That preparation produces a first-release scope with defined functions, owners, and acceptance criteria. It also identifies precisely where data preparation, APIs, or interface integration need engineering work. Mad Devs can help with backend and integration development for an existing product, including product data, API connections, reporting UI integration, and verification against the agreed behavior. Bring the reporting question and the current system's boundaries to that discussion.
Backend development Scope your embedded analytics release Connect product data, access rules, and reporting UX in a defined integration scope. Discuss your project |







