Events Migration

The primary use-case for events is to open interoperability between Plattar and embedded Viewers.

Events allow listening for engine outputs such as onLoad() or onRestart() to create logic that reacts to certain circumstances.

Events can also be used to trigger certain functionalities such as loadScene() to control the inputs into the engine.

Issues with legacy Events

The legacy events framework relies on window.postMessage() to send/recieve events to/from the engine and this poses a number of issues.

  1. The fired events are broadcasts so there may be multiple unintended listeners
  2. The fired events are FAF (Fire and Forget) that causes problems if there are unintended errors along the way, making it impossible to react to those errors
  3. The events framework is difficult to control and often relies on multiple listeners for simplest of tasks which increases the complexity of integrations
  4. Is extremely difficult to maintain and control in a sustainable manner

Plattar Solution

Starting with the Renderer V2 deployment, Plattar is also releasing an in-house built dedicated tool context-messenger to solve all of the problems outlined above.

Context-Messenger is also bundled automatically with all Plattar Web SDK’s starting with the plattar-web SDK. So if you’re using the web SDK, its all setup and ready to go!

How It Works

Context-Messenger allows defining and executing arbitrary JavaScript functions from within the Plattar ecosystem and external websites.

This provides consistency, robustness and performance that is simply not possible with standard window.postMessage() based events.

Context-Messenger is tightly integrated with Plattar’s V2 Rendering engine and is thus available through the PEX Scripting framework, allowing connection of external website logic with internal Plattar Scripts

Limitations

Context-Messenger only works through the https protocol so please ensure your website is hosted on a secure HTTPS Server.

Hello Plattar Sample

This sample uses the plattar-web SDK and PEX Scripting to create a custom, bi-directional bridge between an external website and an Embedded Plattar Viewer.

This sample calls a custom javscript function defined on the external website from within Plattar.

  1. Go to app.plattar.com and create a new empty scene. Note down the scene id as it will be needed shortly.
Create a new empty Scene in the Plattar CMS
Create a new empty Scene in the Plattar CMS
  1. Open the Script Editor in the Plattar CMS and create a new PEX Script called OnLoad using the following JavaScript. Make sure to save your script.
Create a new OnLoad Script on Plattar
// this is executed by Plattar when this script is loaded
this.create = () => {
  return new Promise((accept, reject) => {
    // call out pre-defined script that sits on an external website
    Context.messenger.parent.onLoadFromScript();

		return accept();
  });
}
Creating a new PEX Script in Plattar CMS
Creating a new PEX Script in Plattar CMS
  1. Go back to your original Scene and insert the script you just created by dragging and dropping anywhere in the Scene.
Adding your PEX Script into the Scene
Adding your PEX Script into the Scene
  1. Create a new HTML page using the following sample, ensure to host your HTML on HTTPS and run it. you should see your script executed from Plattar!
External HTML
<html>

<head>
    <title>Context-Messenger</title>
    <!-- load the plattar-web SDK -->
    <script src="https://cdn.jsdelivr.net/npm/@plattar/plattar-web/build/es2019/plattar-web.min.js"></script>
</head>

<body>
    <plattar-viewer id="embed" scene-id="{YOUR-SCENE_ID}" width="500px" height="500px"
        server="staging"></plattar-viewer>
    <script>
        const viewer = document.getElementById("embed");

        if (viewer) {
            // create a new function on our viewer
            // this will be called from our defined PEX Script
            viewer.messenger.self.onLoadFromScript = () => {
                alert("Hello Plattar!");
            };
        }
    </script>
</body>

</html>