Skip to main content
Cloud Apps interact with the JTL platform through two channels:
ChannelTransportDirectionUse case
AppBridge events (coming soon)iframe postMessageBidirectional (app ↔ host)Real-time UI interactions while the app is open
Setup handshakeiframe + AppBridgeHost → your app’s iframeOnboarding when a merchant installs your app
AppBridge events are session-scoped: they only fire while a merchant has your app open in the ERP Cloud. The setup handshake runs once, the first time a merchant configures your app. For a conceptual overview of all three JTL event systems (including SCX polling events for marketplace channels), see the Webhooks & Events page.

​
AppBridge Events

In development: AppBridge publish/subscribe events are in development and not yet available. This section will be updated when the API ships.
AppBridge events will let your app and the host environment exchange messages in real time while the merchant has your app open. Communication is asynchronous and non-blocking, with no HTTP requests or polling involved. The system is designed around two capabilities:
  • Publishing events notifies the host that your app completed an action (for example, a generated product description is ready to insert).
  • Subscribing to events lets your app react when the host’s context changes (for example, the merchant navigates to a different customer record).
Topics will follow a resource:action naming convention so intent is clear from the name. Event payloads are expected to be small (IDs and changed values, not full objects) since the host or your app can always fetch details from the API if needed. For the conceptual overview of how AppBridge events fit alongside lifecycle hooks and SCX polling, see Webhooks & Events.

​
Setup Handshake

The setup handshake runs when a merchant installs your app. Your manifest points at the iframe URL where setup happens: 
{
	"lifecycle": {
		"configurationUrl": "https://your-app.example.com/setup"
	}
}
FieldRole
configurationUrlThe URL JTL loads in an iframe when the merchant clicks Install in the JTL Hub. Your app shows its onboarding UI here and completes the AppBridge handshake.
Inside the iframe, the typical flow is:
  1. The AppBridge initializes and provides a session token.
  2. Your frontend sends the token to your backend for verification.
  3. Your backend verifies the token and stores the tenant connection.
  4. Your frontend calls appBridge.method.call('setupCompleted') to signal that setup is done. For the full implementation, including the React provider, the verification code, and the connect-tenant route in three languages, see App Shell & UI Integration and the From Scratch quickstart.

​
How They Fit Together

The setup handshake runs once, when the merchant first installs your app. AppBridge events will cover real-time interactions during active sessions once the publish/subscribe API ships.

​
What’s Next

App Shell & UI Integration

Full AppBridge API reference and the setup handshake implementation.

Webhooks (Essentials)

Conceptual overview of all three JTL event systems including SCX polling.

Authentication & Login

Verify session tokens during setup and on subsequent backend requests.

Best Practices

Production patterns for error handling, security, and performance.