Skip to main content

Embedded Apps

Join the Beta

For early access to the Embedded Apps private beta, enter your email to join the waitlist

Accelerate time-to-value and deliver seamless user experiences with Superblock Embedded Apps. Rapidly add new functionality to existing internal apps, customize your customer portal to client needs, and more by embedding Superblocks apps in your existing web apps.

Superblocks Embedded Apps let you:

info

This page describes the Superblocks Embedded Apps feature. For guides on how to embed a Superblocks app using an iFrame, see our docs on Embedding Applications in iFrames.

Embed SDKs

Superblocks Embed SDKs make it simple to add Superblocks apps to your existing website or portal. The Embed SDKs let you:

  • Embed apps into your website's code without manually creating and managing iFrames.
  • Communicate with the embed without having to manage cross-frame communication. The Embed SDK handles all cross-domain message passing between your host webpage and embedded Superblocks app.
  • Easily add code to your web-server to request Superblock session tokens for embed users.

The following SDKs are available for embedding Superblocks apps in client-side code:

  • React
  • JavaScript

Interacting with the embed

Superblocks Embedded Apps let you interact with your embedded app by sending data to the embed using properties, update the data sent to your embed and respond to data changes in Superblocks, as well as trigger and respond to events using cross-window messages.

Sending data to the embed

Send data from your host application to your Superblocks app using the properties prop of the SDK. For example, send a customer ID from your web app so your Customer Health shows only data for that customer. Properties are accessible using the {{ Global.properties }} object.

<SuperblocksApp
src="https://app.superblocks.com/embed/application/MY_APP_ID"
properties={{ customerId: selectedCustomer }}
/>

Responding to data changes in Superblocks

Easily configure your Superblocks app to react to property value changes using Value change watcher.

Use Value change watchers to:

  • Re-run APIs when a property changes
  • Update a table's filters when your parent app's query parameters changes
  • Validate user input on change and open a modal to show errors

Respond to property changes using value change watchers

Triggering custom events

Run actions in Superblocks by calling Custom event in your embed's host application. Just create a Custom event in Superblocks and fire it

Create a custom event in the Superblocks editor

const sbApp = useRef();

// Trigger Superblocks custom event to remove this customer
sbApp.trigger("removeCustomer", {
'customerId': customerId
});

Listening for events

Listen for and respond to events emitted by the Superblocks app. Events can include either custom events, or built in Superblocks events.

const sbApp = useRef();

// Listen for customerRemoved event to navigate out of the customer view
sbApp.on("customerRemoved", (event) => {
console.log('Customer removed, going back to /customers');
window.history.pushState(null, null, '/customers');
}

Built in Superblocks events include:

Event NameDescription
APP_LOADEDTriggered when the application finishes loading and becomes interactive.
AUTH_ERRORTriggered 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.
NAVIGATIONTriggered on cross application navigation events.

Authentication

Auth options

When you embed a Superblocks app into your web app, you have several options for how users are authenticated with Superblocks.

  • Public access: user don’t log in to access your application. Anyone on the internet can access the app.
  • Superblocks login: users log in directly to the Superblocks platform. If not logged in, users will be prompted to login before they can access the embedded app.
  • Custom login: users are authenticated outside of Superblocks, for example, through your host application’s identity provider via SSO.

Public access and Superblocks login apps work out of the box, no additional set up required. Custom login requires additional configuration to ensure the embedded user is authorized to access your Superblocks app.

Adding custom authentication

Because the token used to generate session tokens needs to be carefully guarded, user session tokens cannot be created in the browser. Instead follow these steps to log external users into Superblocks:

  1. Implement an endpoint in your web server that requests a session token from Superblocks for the user currently logged in to your web application.

  2. Call this endpoint from your client-side code to fetch the current user's Superblocks token.

  3. Pass the user token to the token property of the Embed SDK.

Sequence diagram showing how to request a session token for an embedded user

The following code shows how to send the user's token to the Superblocks embed.

const CustomerPage = () => {
const [token, setToken] = useState("");

useEffect(() => {
// Generate a Superblocks session token for the currently logged in user
getSBToken().then((token) => setToken(token))
},[]);

return (
<SuperblocksApp
src="https://app.superblocks.com/embed/application/MY_APP_ID"
properties={{ customerId: selectedCustomer }}
token={token}
/>
);
}

getSBToken = () => {
return fetch('https://api.acme.com/v2/superblocks_token')
.then(data => data.json);
}

Customizing user metadata

When requesting a user token from the Superblocks server, define custom metadata that will be associated with the user. Metadata is accessed using {{ Global.user.metadata }} and can be used customize your user's experience in Superblocks.

Because metadata is defined when you generate the user's token and encoded into the user's JWT as custom user claims, metadata cannot be spoofed without invalidating the session token. Superblocks will reject any requests if a bad actor alters any of the JWT's claims.

Managing user access

In Superblocks, users are usually associated with Groups. Group permissions define the what level of access users have to Applications built in Superblocks. They're also used for customizing permissions in code.

Embed users can be associated with Groups when generating the user's session token. Embedded users aren't permanent members of groups, but are granted view access to any of the Applications that group has access to for the duration of their session. The groups specified will also show up in the {{ Global.user.groups }} object and can be used to customize application behavior.