AppBridge Communication

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

The AppBridge is a crucial component provided by the @jtl-software/cloud-apps-core package. Its primary function is to establish a secure and reliable communication channel between your app's frontend (running within an Iframe) and the host JTL cloud service environment (e.g., JTL-Wawi).

This bridge allows your app to interact with the host environment, request data (like session tokens), and trigger actions specific to the context it's running in.

Using AppBridge Communication Methods

Initializing the AppBridge

To use the AppBridge in your React components, you'll need to initialize it and maintain its instance in your component's state. The example below shows initialization at the application root level:

import { createAppBridge } from '@jtl-software/cloud-apps-core';

createAppBridge().then(appBridge => {
  createRoot(document.getElementById('root')!).render(
    <StrictMode>
      <App appBridge={appBridge} />
    </StrictMode>,
  );
});

The initialization process:

1. Import the necessary functions from @jtl-software/cloud-apps-core
2. Use createAppBridge() to establish the connection with the host
3. Once the bridge is created, pass it as a prop to your main App component
4. The App component can then use the bridge instance directly or pass it down to child components
5. This approach ensures the bridge is available immediately when your app renders

Subscribe to Host Events

The subscribe method allows your app to listen for specific events emitted by the host environment.

// Listen for inventory updates
appBridge.event.subscribe("inventory:updated", async (data) => {
  console.log("Inventory updated:", data);
  return { status: "processed" };
});

When the host system triggers an "inventory:updated" event, your callback function will execute with the provided data.

Publish Messages to the Host

The publish method sends data to the host environment under a specific topic.

// Notify the host about completed action
await appBridge.event.publish("order:verification:complete", {
  orderId: "ORD-12345",
  verifiedBy: "app-user"
});

This is useful for informing the host about state changes or actions completed within your app.

Expose Methods to the Host

The expose function makes your app's functions callable by the host environment.

// Make a function available to the host
appBridge.method.expose("calculateShippingCost", (weight, destination) => {
  const baseCost = 5.99;
  const zoneRate = destination === "international" ? 2.5 : 1;
  return baseCost + (0.1 * weight * zoneRate);
});

This allows the host environment to directly use functionality implemented in your app.

Check if Method is Exposed

The isExposed method verifies if a specific function has already been exposed to the host.

// Check if a method is already exposed
if (!appBridge.method.isExposed("calculateTax")) {
  appBridge.method.expose("calculateTax", (amount, rate) => {
    return amount * (rate / 100);
  });
}

This helps prevent errors from attempting to expose the same method multiple times.

Call Host Methods

The call function allows your app to invoke functions provided by the host environment.

// Get user information
const userProfile = await appBridge.method.call("getUserProfile");

// Call a method with parameters
const orderDetails = await appBridge.method.call("getOrderDetails", "ORD-5678");

This enables your app to access host functionality, data, and services.

Communication Flow

The connection facilitates a two-way communication path: your app's appBridge instance talks to the corresponding hostAppBridge instance within the JTL cloud service.

Creating a AppBridge Instance

To establish communication with the host environment, you need to create a AppBridge instance:

import { createAppBridge } from '@jtl-software/cloud-apps-core';

createAppBridge().then(appBridge => {
  createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App appBridge={appBridge} />
  </StrictMode>,
  );
});

Environment-Specific Methods

The AppBridge exposes different methods depending on which environment your app is running in:

Setup Environment Methods

ERP Environment Methods

Calling Methods

To call methods exposed by the host environment, use the call function:

// Basic syntax
appBridge.method.call("methodName", parameter1, parameter2, ...);

// Example: Getting a session token
const sessionToken = await appBridge.method.call("getSessionToken");

Session Token Usage

For more detailed information about working with session tokens in your app, please refer to our Session Token documentation. This guide explains how to properly use the token for authentication, and token lifecycle management.