@superblocksteam/embed
v1.2.0
Published
This repo contains the JavaScript SDK for embedding Superblocks Applications into external websites
Downloads
34
Readme
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.