@superblocksteam/embed

Superblocks Embed

This library is designed to simplify the integration of Superblocks applications within web projects. It provides a custom HTML element that can be used to embed Superblocks applications seamlessly into your web pages, handling initialization, authentication errors, navigation, and bidirectional communication.

Features

• Easy embedding of Superblocks applications into web pages.
• Support for dynamic updates of source URLs, tokens, and properties.
• Custom event handlers for application loading, navigation, and authentication errors.

Installation

NPM

npm install @superblocksteam/embed

Alternatively, you can include the SuperblocksApp library directly from our CDN

<script src="https://prod-cdn.superblocks.com/packages/@superblocksteam/embed@latest/embed.bundle.js"></script>

Usage

Basic Embedding

To embed a Superblocks application, without custom authentication, you just need to set the src to the embed URL for you application. You can find the embed location here.

const sbApp = Superblocks.createSuperblocksEmbed({
    src: "https://app.superblocks.com/embed/applications/:applicationId",
});

document.body.appendChild(sbApp);

Custom authentication

To use custom authentication, generate a token following these instructions. Then pass the token to your embed:

const myToken = await fetch("/api/token");
const sbApp = Superblocks.createSuperblocksEmbed({
    src: "https://app.superblocks.com/embed/applications/:applicationId",
    token: myToken
});

document.body.appendChild(sbApp);

Properties

Pass in arbitrary properties to your embed, which will be accessible in the Superblocks App.

const properties = { myProp1: "test", myProp2: 1 }
const sbApp = Superblocks.createSuperblocksEmbed({
    src: "https://app.superblocks.com/embed/applications/:applicationId",
    properties,
});
document.body.appendChild(sbApp);

Style

Set the style of the iframe that loads the embedded app:

const sbApp = Superblocks.createSuperblocksEmbed({
  src: "https://app.superblocks.com/embed/applications/:applicationId",
  style: "height 400px; width: 100%"
})

Update the style:

sbApp.style.border = "1px solid black;"

Dynamically Updating Properties

You can dynamically update the token and properties of your Superblocks application after it has been embedded, without causing the full embed to reload:

const sbApp = Superblocks.createSuperblocksEmbed({
    src: "https://app.superblocks.com/embed/applications/:applicationId",
    id: "sb-app"
});
document.body.appendChild(sbApp);
...
const sbApp = document.getElementById("sb-app");
sbApp.token = "newAuthToken";
sbApp.properties = { myProp1: "newValue" };

API Reference

To enhance the readability and structure of your API Reference section, incorporating type information for clarity and completeness, you might format it as follows:

---

Methods

• createSuperblocksEmbed(attributes: SuperblocksAppAttributes): SuperblocksAppElement

  Creates and returns a new superblocks-app element configured with the specified attributes.

Attributes

SuperblocksAppAttributes includes the following properties:

• 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 (optional): Style passed to the iframe element. 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 = createSuperblocksEmbed(attributes);
sbApp.trigger("eventName", { arg1: "foo", arg2: "bar" });

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 being navigated to (if applicable).

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

  • error: string: Description of the authentication error.