Interactive Embedding

Once you have a basic embed set up, you'll likely want to start customizing your app's behavior by adding interactivity to your embedded app. Use interactivity to:

• Send data to your app and use it to customize what users see
• Respond to property changes when new values are passed from the host app
• Listen for events that are triggered by the Superblocks app
• Trigger events in the Superblocks app based on user behavior in the host app
• Control the color scheme of the Superblocks app from the host app

Send data to the embed

Send data to your embedded app to customize what users see based on properties of the host application. For example, send filters in the browser's URL to filter an API response or sort a table.

To start sending data:

1. Define the properties your app will accept in the Embedding panel. Click the + icon to add a new property

   

2. Add a Test value for your property. This value will be used when developing your app in the editor

   

3. Reference the property using the binding syntax. Embedded properties are accessed through the Embed namespace, for example {{ Embed.PropName.value }}

4. Test your app. When you're ready to expose the property to the host app, commit & deploy your app

   info

   After deploying your app to expose a new Embed property, properties not passed by the host app will be treated as null.

5. Go to your website code and send a value to the property from the host app

   React

   import React from 'react';
   import { SuperblocksEmbed } from '@superblocksteam/embed-react';
   
   const AppWithEmbed = () => {
   
       const properties = {
           startTs: moment().startOf('month').toISOString(),
           endTs: moment().toISOString()
       };
   
       return <>
           <SuperblocksEmbed
               src='https://app.superblocks.com/embed/applications/<APP_ID>'
               properties={properties}
           />
       </>;
   }

   JavaScript

   const properties = {
       startTs: moment().startOf('month').toISOString(),
       endTs: moment().toISOString()
   };
   
   const sbApp = Superblocks.createSuperblocksEmbed({
       id: "sb-app",
       src: "https://app.superblocks.com/embed/applications/<APP_ID>",
       properties,
   });
   document.body.appendChild(sbApp);

Respond to property changes

The data you send when initializing your embed will likely change as your user interacts with the host app.

When a property value changes, you can respond in Superblocks by adding an onChange event handler for the property. Read our docs on Event Handlers to learn more about actions you can perform on value change.

Listen for events

You can use event listeners to create actions based on events that happen in your Superblocks app. The event listener registers a callback handler, that handler method gets called when an event occurs.

Supported events

Embedded apps support the following event types out of the box:

Event Name	Handler	Description
AppLoadedEvent	onAppLoaded	Triggered when the application finishes loading and becomes interactive.
AuthErrorEvent	onAuthError	Triggered when the user's session expires or upon login if there is an authentication error. Will also trigger if the user clicks on a link that tries to bring them to a Superblocks Application they're not allowed to access.
NavigationEvent	onNavigation	Triggered on cross application navigation events.

Add an event listener

Listen for events by registering a callback handler with your embed component.

The follow code shows an example of how to listen and respond to events emitted by the embed:

React

import React from 'react';
import { SuperblocksEmbed } from '@superblocksteam/embed-react';

const AppWithEmbed = () => {

    const handleAuthError = (event) => {
        console.log('User authentication with Superblocks failed');
    };

    return <>
        <SuperblocksEmbed
            src='https://app.superblocks.com/embed/applications/<APP_ID>'
            onAuthError={handleAuthError}
        />
    </>;
}

JavaScript

 async function handleAuthError(event) {
     console.log('User authentication with Superblocks failed');
 }

const sbApp = document.getElementById("sb-app");
sbApp.onAuthError = handleAuthError;

Change the color scheme

To dynamically adjust the Superblocks color scheme (light or dark mode set in Themes) from the host application, pass a colorScheme prop to the embedded application.

info

The code below shows a basic example of how to pass a color scheme to Superblocks. You should use your own tools / packages to determine your host app's color scheme and update it across the app.

React

import React, { useState } from 'react';
import { SuperblocksEmbed } from '@superblocksteam/embed-react';

const AppWithEmbed = () => {

    const [colorScheme, setColorScheme] = useState<"light" | "dark">("light");

    return <>
        {/* logic to update colorScheme from host app component action */}
        <button
            onClick={() =>
              setColorScheme(colorScheme === "light" ? "dark" : "light")
            }
        >
        Toggle Color Scheme
        </button>

        {/* corresponding colorScheme passed into SuperblocksEmbed */}
        <SuperblocksEmbed
            src='https://app.superblocks.com/embed/applications/<APP_ID>'
            colorScheme={colorScheme}
        />
    </>;
}

JavaScript

<body>
   <button id="change-color-scheme">Toggle color scheme</button>
   <div id="embed-wrapper" />
   <script>
       // create embed
       const sbApp = Superblocks.createSuperblocksEmbed({ 
          src: "", 
          colorScheme: "light",
          id: "sb-embed"
       });
       document.getElementById("embed-wrapper").appendChild(sbApp);
       document.getElementById("change-color-scheme").addEventListener('click', () => {
          const sbApp = document.getElementById('sb-embed');
          sbApp.colorScheme = sbApp.colorScheme === "light" ? "dark" : "light";
       });
   </script>
</body>