The ISM Webapp Iframe Communication API (version 1.0.0) enables secure cross-origin communication between an embedded ISM (Interactive Space Manager) web application and its parent page using the Window.postMessage() mechanism. This JavaScript library facilitates interaction with the ISM webapp.
¶ Overview
The API is provided as a JavaScript library that you include in your code. It requires an iframe to host the ISM webapp and initializes a communication channel between the parent page and the embedded application.
¶ Including the Library
Include the minified JavaScript library in your HTML:
<script type="text/javascript" src="https://apps.zondavirtual.com/api/webappISM-1.0.min.js"></script>¶ Demo Page
A demonstration of the API is available at: https://apps.zondavirtual.com/demo/webapp_communication/ism/index.html
¶ Initialization
To use the API, initialize it by creating an instance of ZONDA.WebappISMApi with a reference to the iframe hosting the ISM webapp and a callback function to handle initialization results.
¶ Iframe Setup
The ISM webapp must be loaded in an iframe. Set the iframe's src attribute to the ISM application URL, which typically includes a plan ID. For example:
<iframe id="ismIframe" style="height:100%;width:100%" src="https://apps.zondavirtual.com/alphamap/index.html?OLAId=2542609e-fa60-40d1-b191-b3b7364c88f3&noheader" onload="iframeLoaded(event)"></iframe>The API requires time to initialize as it waits for the ISM webapp to load. During this period, you can display a placeholder image or a gray background (as shown in the demo) to improve the user experience. Once initialization is complete, the specified callback function is invoked with a success or error message.
You can confirm that the connection has been successfully established by observing the following messages in the browser console:
- Loading: Loading ISM Webapp IFrame Communication API v1.0.0...
- Success: [SUCCESS] ISM API connected to ISM application via iframe [ismIframe] in 1.988 seconds.
¶ Parameters
- IFrame* (DOM Element or String): A reference to the iframe DOM element or its ID.
- CallbackFunction (Function): A callback function to handle initialization results.
Parameters marked with an asterisk () are mandatory.
¶ Example Initialization
var webappISM;
var iframeLoaded = (e) => {
webappISM = new ZONDA.WebappISMApi(document.getElementById("ismIframe"), (result) => {
if (result.success) {
console.log(result.message); // e.g., "api loaded in 1.833 sec"
} else {
console.log(result.message); // e.g., "error message"
}
});
};
¶ Available Variables
The following instance variables are available on a WebappISMApi object after initialization:
- iframe (DOM Element): The iframe element hosting the ISM webapp, passed during initialization.
- webappUrl (String): The URL of the ISM webapp loaded in the iframe.
- name (String): The API identifier, set to
'ISM'.
¶ Available Functions
Currently, the WebappISMApi does not define any additional instance methods beyond the loaded call back information. Future updates may add ISM-specific functionality.
¶ Message IDs
The API returns the following message IDs in responses:
- S_002: "ISM API connected to [ismIframe]."
- S_003: "ISM API connected to [ismIframe]. ISM webapp loaded in 1.712 seconds!"
- E_001: "IFrame [ismIframe] doesn't exist."
- E_002: "The connection with the ISM application is not established"
- E_003: "ISM is not ready yet!"
- E_005: "Invalid origin: [Parent Origin]"
- E_006: "IFrame [ismIframe] is not an IFrame"
- E_007: "ISM Api trying to connect to a bad webapp."
- E_010: "SessionId or userId is required"
- E_011: "userId is required"
¶ Console Errors
The following error may appear in the console if initialization fails:
- "IFrame [ismIframe id] doesn't exist.": Indicates that the iframe reference is invalid or missing.
¶ Security Considerations
The following considerations are critical for secure usage of the API
- The API validates the origin of incoming messages using isValidOrigin(event.origin) to ensure secure cross-origin communication.
- Only messages with a matching apiId ('ISM') are processed.
- Developers should ensure the iframe source URL is trusted and properly configured.
- Using multiple IFrame Communication API on the same page should work without conflic even if multiple
Window.postMessage()event are managed in each.
https://apps.zondavirtual.com/demo/webapp_communication/isp_ifp.html
¶ Troubleshooting
Common issues and their solutions:
- Iframe Not Found: Ensure the iframe ID or DOM reference is correct. Check for typos or timing issues (e.g., referencing the iframe before it is added to the DOM).
- Connection Issues: Verify that the ISM webapp URL is accessible and that the parent page and iframe are served over HTTPS to avoid mixed content errors.
- Callback Not Triggered: Ensure the callback function is properly defined and that the ISM webapp has finished loading.
¶ Version History
- 1.0.0: Initial release, providing core communication functionality.