Skip to content
How-toForVendor ownerVendor developer⏱ About 15 min
Before you start:
  • Owner or developer role
  • a product hosted by you
  • provisioning set up

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 ​

  1. List your screens in the version. In Vendor portal → Products, open the product's version and add nav_items to 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" }
      ]
    }
    FieldMeaning
    keylower-case letters, digits and dashes; stays the same between versions
    titlethe menu entry's name
    route or urla path on your launch address's site, or a full https address
    iconan mdi- icon name (optional)
    parentthe key of another of your items, to sit under it (optional)
    openiframe: inside BMA. tab: a new browser tab (the default)

    At most 20 items.

  2. Let BMA show your pages in a frame (for iframe items):

    • Send Content-Security-Policy: frame-ancestors https://bma.botmodepro.com (add your own addresses if you also frame yourself), and don't send X-Frame-Options: DENY or SAMEORIGIN on 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.
  3. 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 your POST /sso with target set to the screen's address; answer with a url that lands there.
    • none: BMA opens the address as it is.
  4. Send the version for review. A change to nav_items is 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 to frame-ancestors.
  • An iframe screen 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 to iframe.
  • A tab screen 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 seeIt meansDo this
"This screen is no longer part of the product"a menu entry whose key isn't in the live versionkeep keys stable between versions
"This product has no launch address"a route item, but no https launch_urlset launch_url, or use a full url
"Sign-in to this product is not set up yet"jwt or vendor_sso without a provisioning secretcreate the secret in Provisioning
A blank frameyour page refused to be framedstep 2, or set open to tab