Multi-App Integration Guide

Multi-App Support

The JavaScript SDK v1.9.0 supports running multiple Webex Connect app assets on the same website URL across different browser tabs. For example, a user can be logged into Asset A in one tab and Asset B in another tab on the same domain, with each operating independently. Within a single tab, developers can switch between assets using uninit() followed by startup() with a different config.

Each app asset gets:

• Its own Service Worker scope.
• Its own MQTT connection for real-time messaging.
• Its own push notification routing.
• Its own isolated storage. No data is shared between assets.

Setup

Step 1: Define configurations for each app in imi-environments.js. See section 3.1.

Step 2: Initialize the desired app using startup() with the config:

// Either use the imiEnvironments file.
IMI.IMIconnect.startup(null, imiEnvironments["APP_A"]);

// Or pass the config object directly.
var APP_A = {
    "asset": {
        "appId": "YOUR_APP_ID_A",
        "appSecret": "< your App Secret here >",
        "pathConfig": { "assetPath": "/assets/", "root": "/" }
    },
    "imiclient": {
        "authdomain": "https://auth-a.example.com",
        "rtmsdomain": "wss://rtms-a.example.com",
        "shouldRequestNotificationPermission": false
    },
    "sw": {
        "config": {
            "appid": "YOUR_APP_ID_A",
            "serverUrl": "https://server-a.example.com"
        }
    }
};

IMI.IMIconnect.startup(null, APP_A);

Step 3: Use the SDK normally: register, connect, and handle messaging.

var deviceProfile = new IMI.ICDeviceProfile(deviceID, userID);

IMI.IMIconnect.register(deviceProfile, {
    onSuccess: function() {
        var messaging = IMI.ICMessaging.getInstance();
        messaging.setICMessagingReceiver({
            onConnectionStatusChanged: function(status) {
                console.log("Connection status:", status);
            },
            onMessageReceived: function(message) {
                console.log("Message received:", message);
            }
        });
        messaging.connect();
    },
    onFailure: function(err) {
        console.log("Registration failed:", err);
    }
});

Switching Apps

To switch from one app to another on the same page:

// 1. Tear down the current app
await IMI.IMIconnect.uninit();

// 2. Initialize the new app
IMI.IMIconnect.startup(null, imiEnvironments["APP_B"]);

// 3. Register and connect as usual
var deviceProfile = new IMI.ICDeviceProfile(deviceID, userID);
IMI.IMIconnect.register(deviceProfile, registerCallback);

Note: Always call uninit() before calling startup() with a different app config. Calling startup() without uninit() while another app is active will result in unexpected behavior.

Service Worker Architecture

The SDK uses a single physical sw.min.js file that serves all apps. Each app registers its own Service Worker instance at a unique scope:

your-website/
+-- sw.min.js                    single file at root
+-- (SDK registers internally)
    +-- /sw/APP_A/               scope for App A
    +-- /sw/APP_B/               scope for App B

Each scoped Service Worker instance maintains:

• An independent MQTT connection to the app's messaging broker.
• Its own client-tab mapping for push notification routing.
• Isolated IndexedDB storage for connection state.

Note: sw.min.js file placement has not changed. It must remain at the path specified by pathConfig.root. The SDK handles per-app scoping automatically.

Connection Lifecycle

Push Notifications In Multi-App

Each app receives only its own push notifications. The Service Worker routes notifications to the correct app instance using an internal client-to-app mapping.

• When a push notification arrives, only the tabs registered for that app are notified.
• Notification click focuses the correct tab for that app.
• Foreground push display is controlled per app.