Appearance
Put your product in the customer's BMA menu
When an organization buys your hosted product, BMA can add your screens to the menu of everyone in that organization, under Vendor apps › your company › category › your product. Each screen opens inside BMA, next to the rest of their work, or in a new tab. You describe the screens in your product version; BMA signs each user in to them the same way it does for Open.
We encourage you to support opening inside BMA. People stay in the place they already work all day, they find your product in their menu instead of a bookmark, and your listing shows a Works inside BMA badge.
What you need
- A hosted product (remote instance or set-up wizard) with provisioning set up: see Provisioning and webhooks.
- Pages your site allows BMA to show in a frame (step 2), for screens that open inside BMA.
Steps
List your screens in the version. In Vendor portal → Products, open the product's version and add
nav_itemsto its Integration JSON:json{ "launch_url": "https://app.example.com/start", "sso_mode": "jwt", "nav_items": [ { "key": "dashboard", "title": "Dashboard", "route": "/dashboard", "icon": "mdi-view-dashboard", "open": "iframe" }, { "key": "reports", "title": "Reports", "route": "/reports", "icon": "mdi-chart-bar", "open": "iframe" }, { "key": "settings", "title": "Settings", "url": "https://app.example.com/settings", "open": "tab" } ] }Field Meaning keylower-case letters, digits and dashes; stays the same between versions titlethe menu entry's name routeorurla path on your launch address's site, or a full https address iconan mdi-icon name (optional)parentthe keyof another of your items, to sit under it (optional)openiframe: inside BMA.tab: a new browser tab (the default)At most 20 items.
Let BMA show your pages in a frame (for
iframeitems):- Send
Content-Security-Policy: frame-ancestors https://bma.botmodepro.com(add your own addresses if you also frame yourself), and don't sendX-Frame-Options: DENYorSAMEORIGINon those pages. - Inside a frame, browsers treat your site as third-party. Set your session cookie with
SameSite=None; Secure, or sign the user in from BMA's token on each open (step 3). - Pop-ups, downloads, forms and dialogs work in the frame. Links that leave your site should open a new tab.
- Send
Sign people in. Every open asks BMA for a fresh, signed address:
jwt: BMA opens the screen's address with?token=<JWT>(valid 120 seconds; see Sign-in).vendor_sso: BMA calls yourPOST /ssowithtargetset to the screen's address; answer with aurlthat lands there.none: BMA opens the address as it is.
Send the version for review. A change to
nav_itemsis always reviewed. Once it's approved, buyers see the new menu the next time they load BMA.
What buyers see
- Vendor apps › your company › category › your product › Dashboard in their BMA menu (the category is your listing's first category; without one, Other). Each organization's administrators choose where Vendor apps sits in their menu, and may show a product to some of their groups only. It's shown while the subscription is trialing, active or past due and their account is set up.
- Host platforms that sell through BMA show the same screens in their own menus (they read them through the host API). Their users reach you as
host:<host id>:<user id>, and those platforms frame your pages from their own address: ask the host for it and add it toframe-ancestors. - An
iframescreen fills BMA's work area, with Open in new tab and Reload above it. If your page refuses to be framed, they see a blank area and a hint to use Open in new tab, so test it before you switch an item toiframe. - A
tabscreen opens in a new tab; if a pop-up blocker stops it, Open in new tab tries again. - Your listing shows Works inside BMA when at least one item opens inside BMA.
If something goes wrong
| They see | It means | Do this |
|---|---|---|
| "This screen is no longer part of the product" | a menu entry whose key isn't in the live version | keep keys stable between versions |
| "This product has no launch address" | a route item, but no https launch_url | set launch_url, or use a full url |
| "Sign-in to this product is not set up yet" | jwt or vendor_sso without a provisioning secret | create the secret in Provisioning |
| A blank frame | your page refused to be framed | step 2, or set open to tab |