App Bridge Overview

Embedded apps run inside the Shoplazza merchant admin as iframes. However, pages within the iframe are isolated from the outer admin, making it impossible to directly manipulate the admin's navigation, top bar, etc. Shoplazza App Bridge is the JavaScript library that bridges this isolation — after introducing it in your app's frontend, code inside the iframe can call the admin's navigation redirect (Redirect), back link (Backlink), save bar (SaveBar), and obtain the authentication token (Session Token) needed for calling Open API. This makes your app feel like a native Shoplazza admin page, so merchants never feel like they've left Shoplazza.

When does your app need App Bridge?

Scenario	Required?
App UI is embedded in the Shoplazza merchant admin (inside an iframe)	✅ Required
Need to trigger Shoplazza top navigation/Redirect from within the app	✅ Required
App is a standalone site that merchants access via an external link	❌ Not needed
Pure backend service without UI (only calls Open API via OAuth)	❌ Not needed

Key point: Is your app displayed as an iframe in the merchant admin? If yes, App Bridge is almost certainly required.

Core capabilities map

Capability	Usage	Documentation
Session Token	Authentication for embedded apps — frontend obtains JWT, backend verifies it, securely calls Open API	Session Token
Backlink	Adds a "back to previous level" link in the Shoplazza top navigation	Backlink
SaveBar (Contextual Save Bar)	Form dirty checking + unified "Save/Discard" action bar at the top	SaveBar
Redirect	Controls merchant admin main navigation jumps (preserves iframe context)	Redirect

Relationship with Session Token

Browser (iframe)               Your App Backend
       │
       │ ① getSessionToken(clientID)
       │    (Shoplazza issues JWT, valid for 1 minute)
       │
       │ ② fetch('/api/...', { Authorization: 'Bearer <jwt>' })
       │ ───────────────────────────────►
       │                                  ③ Verify JWT
       │                                  ④ Use persistent access_token to call Open API
       │                                  ⑤ Return business data
       │ ◄───────────────────────────────

Session Token lifespan is fixed at 1 minute — fetch a new one for every request, never cache it.

Installation

App Bridge is published as the npm package shoplazza-app-bridge. Install it in your embedded app's frontend project:

npm install shoplazza-app-bridge --save

Initialize it in your app's entry file (recommended to execute once before the page mounts):

import { app } from 'shoplazza-app-bridge';

app.init();

app.init() sends an APP::ENABLED message to the host (Shoplazza merchant admin) to establish communication and starts listening for events sent back by the admin. After initialization, you can use all available capabilities — see the individual documentation pages linked in the "Core capabilities map" above for detailed usage.

Consistency with Shoplazza Admin UI

By using App Bridge:

• Your app looks like a "native page" of the Shoplazza admin, providing a consistent mental model for merchants
• Browser history, URL navigation, and save prompts follow the patterns merchants are familiar with
• Multi-language and dark mode (if supported by Shoplazza) automatically follow the host

Differences from external-link apps

	Embedded (App Bridge)	External-link app (no App Bridge)
Merchant entry	Clicked from the left navigation in Shoplazza admin	Leaves Shoplazza to an independent site
Visual consistency	Consistent with Admin UI	Independent design
Authentication	Session Token + persistent access_token	access_token only
Recommended scenario	Apps frequently used within the Shoplazza workflow	Tools used occasionally or requiring a standalone UX

Related

• Session Token deep dive
• App type selection
• OAuth authentication — obtaining access_token during the app's first installation