Superblocks Embed React Library

The Superblocks Embed React Library allows you to seamlessly integrate Superblocks applications into your React application by embedding them within an iframe. This library provides a simple yet powerful interface for embedding, managing events, and interacting with the embedded application.

Features

• Dynamic Embedding: Easily embed Superblocks applications using a React component.
• Event Handling: Listen to various events from the embedded application such as app loaded, authentication errors, and navigation events.
• Secure Communication: Ensures secure message passing between your application and the embedded Superblocks application.

Installation

To install the Superblocks Embed library, run the following command in your project directory:

npm install @superblocksteam/embed-react

Usage

1. Import the Component: First, import the SuperblocksEmbed component from the library.

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

2. Embed a Superblocks Application: Use the SuperblocksEmbed component in your React application, passing the required props.

   <SuperblocksEmbed src="https://app.superblocks.com/embed/applications/:APP_ID" />

3. Custom Authentication: Pass a token generated from the Superblocks token endpoint to the embed

   <SuperblocksEmbed
     src="https://app.superblocks.com/embed/applications/:APP_ID"
     token=":ID_TOKEN"
   />

4. Properties Pass in a properties object. These will be accessible in your Superblocks App using {{embed.propertyName.value}}

   <SuperblocksEmbed
     src="https://app.superblocks.com/embed/applications/:APP_ID"
     token=":ID_TOKEN"
     properties={{ property1: "test", property2: 123 }}
   />

Props

• src: string: The URL of the Superblocks application to embed.
• id?: string (optional): An identifier for the embed element.
• token?: string (optional): Authentication token for the Superblocks application.
• properties?: Record<string, unknown> (optional): Initial properties to pass to the Superblocks application.
• style?: React.CSSProperties (optional): Styles set on the embedding iframe. By default, height and width are set to 100%.
• onAppLoaded?: (event: AppLoadedEvent) => void (optional): Callback for the app loaded event.
• onNavigation?: (event: NavigationEvent) => void (optional): Callback for navigation events.
• onAuthError?: (event: AuthErrorEvent) => void (optional): Callback for authentication error events.
• onEvent?: (eventName: string, payload: object) => void (optional): Callback for custom events emitted by the embedded application. Payload is an object of argument name to value.

Methods

Trigger custom events on the embedded application using the trigger function:

const sbApp = useRef(null);
const triggerEvent = () => sbApp.current.trigger("eventName", { arg1: "foo", arg2: "bar" });

return <SuperblocksEmbed src={src} ref={sbApp} >

Event Types

• AppLoadedEvent: Fired when the Superblocks application has loaded successfully.

  • id: string: Identifier of the loaded application.
  • name: string: Name of the loaded application.

• NavigationEvent: Fired on navigation events within the Superblocks application.

  • url: URL being navigated to.
  • appId?: string (optional): Identifier of the application.

• AuthErrorEvent: Fired when there is an authentication error within the Superblocks application.

  • error: string: Description of the authentication error.

Error Handling

If there is an issue with initializing the embed or if the provided properties are invalid, the component will render the error message.