Custom Embedded Dashboard
Replace the built-in merchant dashboard with one you build and host yourself. ShipStream shows your page in a frame on the Client Portal Dashboard and on Dashboard -> Client Dashboard in the Admin UI. Each time it loads the frame, ShipStream signs a short-lived JSON Web Token (JWT) that says which Merchant, and in the Admin UI which Warehouses, the viewer may see. Your dashboard verifies the token with a secret key it shares with ShipStream, then loads its figures from the ShipStream API.
The same setup can also replace the Admin UI Dashboard with a warehouse view of your own. See Warehouse Hub.
Who can set it up
Admin UI users whose role includes the System -> Configuration -> Client Dashboard permission can change these settings. No role gets it automatically. Grant it under System > Users > User Roles. See User Roles.
The URL, Secret Key and timing settings apply to every Merchant. Only Enabled can be set per Merchant.
How it works
- A user opens the dashboard. ShipStream signs a token for that user's Merchant and Warehouses, and loads your URL in a frame with the token after
#token=. - Your page reads the token from the address and sends it to your server with each request.
- Your server verifies the token with the Secret Key, then calls the ShipStream API with its own credentials, limited to the Merchant and Warehouses named in the token.
- Every Auto-Refresh Period while the page is visible, ShipStream replaces the token with a new one.
The token is placed after #, so browsers never send it to your server in the page request, and it is left out of Referer headers.
Set up the dashboard
- Host your dashboard on HTTPS. Browsers refuse to show an
http://page inside ShipStream. - Allow ShipStream to show it in a frame by sending
Content-Security-Policy: frame-ancestors https://<your ShipStream address>, and noX-Frame-Optionsheader. - Generate a random secret of at least 32 bytes, for example with
openssl rand -base64 48, and give it to your dashboard's server. - In ShipStream, open System -> Configuration -> Clients -> Dashboard with Current Configuration Scope set to Global, and fill in Custom Embedded Dashboard (beta):
Field What to enter Secret Key The secret from step 3. URL Your dashboard's address, such as https://dash.example.com/view. Query parameters in it are kept.JWT Expiration How many seconds each token is valid. Default 300. Make it longer than the Auto-Refresh Period, such as 600, so a token is still valid when the next one arrives. Auto-Refresh Period How often ShipStream sends a new token while the page is visible, in seconds. Default 300, from 60 to 86400. Use for Admin Dashboard Leave at No unless your dashboard serves the Warehouse Hub. - Set Enabled to Yes. At Global scope this turns the embedded dashboard on for every Merchant. To try it with one Merchant first, leave it at No here, choose that Merchant under Current Configuration Scope, and set Enabled to Yes there.
- Click Save Config, then open Dashboard -> Client Dashboard and choose the Merchant.
A Merchant without Enabled keeps the built-in dashboard. If the URL or Secret Key is missing, every Merchant keeps the built-in dashboard.
The frame address
ShipStream loads your URL with query parameters added and the token after #:
| Page | Address |
|---|---|
| Client Portal Dashboard | https://dash.example.com/view?website_hash=…#token=… |
| Admin UI Dashboard -> Client Dashboard | https://dash.example.com/view?website_hash=…&warehouse_hash=…#token=… |
| Admin UI Dashboard, with Use for Admin Dashboard | https://dash.example.com/view/hub/warehouse?scope_hash=…#token=… |
The *_hash values change whenever the Merchant or Warehouse selection changes, so the browser loads a fresh page instead of reusing the old one. Do not use them to decide what to show. Read the Merchant and Warehouses from the verified token.
When only the token changes, the browser does not reload your page. It fires a hashchange event, and your page should read the new token then.
The token
The token is signed with HS256 using the Secret Key. A merchant dashboard token holds:
| Claim | Meaning |
|---|---|
website_id | The Merchant's ID, as a string. It is the merchant_id used by the Global API. |
warehouse_ids | Admin UI Client Dashboard only: the Warehouse IDs selected in the page header. Show figures for these Warehouses only. When it is missing, the viewer may see all of the Merchant's Warehouses. |
locale | The viewer's locale, such as en_US. |
media.product_base_url | Prefix for a Product's thumbnail path, for showing product images. |
media.placeholder_url | Image to show when a Product has no thumbnail. |
iat, exp | Issue and expiry times, in seconds since 1970 (UTC). |
A Client Portal token never holds warehouse_ids, because a Merchant's users see every Warehouse that serves the Merchant.
On your server:
- Accept HS256 only, and reject tokens whose signature or
expdoes not check out. Allow up to a minute of clock difference. - Require
website_idfor a merchant dashboard. A Warehouse Hub token hasscopeset toadminand nowebsite_id, so the two can never be confused. - Limit every API call to
merchant_idequal towebsite_id, and towarehouse_idswhen present. - Keep your ShipStream API credentials on the server. Never send them to the browser.
- Treat the token like a password: do not log it or store it.
Example with Node.js and the jose library:
import { jwtVerify } from 'jose';
const secret = new TextEncoder().encode(process.env.SHIPSTREAM_DASHBOARD_SECRET);
// Returns what the viewer may see, or throws when the token is not valid.
export async function readViewer(authorizationHeader) {
const token = (authorizationHeader || '').replace(/^Bearer /, '');
const { payload } = await jwtVerify(token, secret, { algorithms: ['HS256'], clockTolerance: 60 });
if (payload.scope === 'admin') {
return { hub: true, warehouseIds: payload.warehouse_ids, merchantIds: payload.website_ids };
}
if (typeof payload.website_id !== 'string') {
throw new Error('Not a dashboard token');
}
return { hub: false, merchantId: Number(payload.website_id), warehouseIds: payload.warehouse_ids ?? null };
}
Talking to ShipStream from the page
Browsers often block cookies inside a frame from another site, so keep the token in memory and send it to your server in an Authorization: Bearer header. Remove it from the address once read:
const SHIPSTREAM_ORIGIN = 'https://example.shipstream.app'; // your ShipStream address
let token = null;
function takeToken() {
const next = new URLSearchParams(location.hash.slice(1)).get('token');
if (next) {
token = next;
history.replaceState(null, '', location.pathname + location.search);
}
}
takeToken();
window.addEventListener('hashchange', () => {
takeToken();
loadFigures(); // fetch your data again with the new token
});
The page and ShipStream exchange messages with postMessage. ShipStream accepts messages only from the origin of the configured URL and sends messages only to it. Check event.origin against your ShipStream address on your side as well.
| Message from your page | What ShipStream does |
|---|---|
{ type: 'resize', height: 1240 } | Sets the frame's height in pixels, from 1 to 20000. Send it whenever your content's height changes. Until the first one arrives, the frame fills the rest of the window. |
{ type: 'iframe-ready' } | Replies with the address of the ShipStream page as a string. ShipStream also sends it each time the frame loads. |
{ type: 'navigate', route: 'sales_order/view', params: { order_id: '1234' } } | Opens that ShipStream page in place of the dashboard. See below. |
function send(message) {
window.parent.postMessage(message, SHIPSTREAM_ORIGIN);
}
new ResizeObserver(() => {
send({ type: 'resize', height: document.documentElement.scrollHeight });
}).observe(document.documentElement);
The frame cannot open new windows or navigate ShipStream itself. Use navigate for links into ShipStream. ShipStream checks the route, its parameters, and that the record belongs to the Merchant, and ignores anything else:
| Route | Parameters | Opens |
|---|---|---|
sales_order/view | order_id: the Order's id from the Global API, not its order number | The Order |
sales_order_shipment/view | shipment_id: the Shipment's id | The Shipment |
catalog_product/edit | id, or sku | The Product |
sales_order/index | None | The Orders grid |
sales_shipment/index | None | The Shipments grid |
sales_package/index | None | The Packages grid |
catalog_product/index | None | The Products grid |
delivery/index | None | The Deliveries grid |
work/index | None | The Work Orders grid |
In the Admin UI, a grid opens for the Merchant and the Warehouses selected in the page header.
Warehouse Hub
With Use for Admin Dashboard set to Yes, the Admin UI Dashboard shows your page instead of the built-in dashboard. ShipStream adds /hub/warehouse to your URL's path, so https://dash.example.com/view becomes https://dash.example.com/view/hub/warehouse. Turn it on only when your dashboard serves that page.
A Warehouse Hub token holds:
| Claim | Meaning |
|---|---|
scope | Always admin. |
warehouse_ids | The Warehouse IDs selected in the page header that the user may see. |
website_ids | The Merchant IDs the user may see, or null when the user may see every Merchant. |
admin_user_id | The ID of the Admin UI user, for your own records. Do not use it to decide what to show. |
timezone | The time zone of the selected Warehouse, such as America/New_York, or the default time zone when several are selected. Use it for "today" and other day boundaries. |
locale, media, iat, exp | As in the merchant dashboard token. |
The hub can open the sales_order/index, sales_shipment/index, sales_package/index, catalog_product/index, delivery/index and work/index grids, and also cyclecount/index, putaway/index, relocation/index and replenishment_task/index, all without parameters. It cannot open single records.