BlockletService
The BlockletService provides methods to access the metadata of a blocklet. This metadata, represented by the Blocklet object, contains essential information such as the application's name, URL prefix, version, and component mount points.
The service can retrieve this information in two primary ways:
- Client-Side: By reading the global
window.blockletobject, which is automatically available when your code is running inside a blocklet's frontend. - Remote Fetch: By fetching the blocklet's metadata from a specified base URL. This is useful for server-side contexts or when interacting with a blocklet from an external application.
To improve performance, the service implements an in-memory cache for remotely fetched blocklet data, which lasts for 60 seconds.
Methods#
getBlocklet()#
Fetches the blocklet's metadata object. The behavior of this method changes based on the provided arguments.
- When called without arguments on the client-side, it synchronously returns
window.blocklet. - When called with a
baseUrl, it asynchronously fetches the metadata from the remote URL.
Parameters
Returns
Examples
Get Blocklet on Client-Side
// This code assumes it's running in a blocklet's frontend environment
async function logBlockletName() {
try {
// On the client, getBlocklet() can be synchronous if data is preloaded
const blocklet = await sdk.blocklet.getBlocklet();
console.log('Blocklet Name:', blocklet.appName);
} catch (error) {
console.error('Failed to get blocklet info:', error);
}
}
logBlockletName();Fetch Blocklet from a URL
async function fetchRemoteBlocklet(url) {
try {
console.log(`Fetching blocklet info from ${url}...`);
const blocklet = await sdk.blocklet.getBlocklet(url);
console.log(`Successfully fetched: ${blocklet.appName} v${blocklet.version}`);
// Fetch again, this time it should be from cache
const cachedBlocklet = await sdk.blocklet.getBlocklet(url);
console.log('Fetched from cache:', cachedBlocklet.appName);
// Force a refetch, bypassing the cache
const freshBlocklet = await sdk.blocklet.getBlocklet(url, true);
console.log('Force-refetched:', freshBlocklet.appName);
} catch (error) {
console.error('Failed to fetch remote blocklet:', error);
}
}
fetchRemoteBlocklet('https://store.blocklet.dev');loadBlocklet()#
This is a client-side utility method that dynamically injects the __blocklet__.js script into the document's <head>. This script populates the window.blocklet object, making the metadata available globally. This is particularly useful for applications that are not blocklets themselves but need to interact with one.
Note: This method will fail if called in a server-side (Node.js) environment.
Returns
Example
Dynamically Load Blocklet Script
async function initializeBlockletData() {
try {
await sdk.blocklet.loadBlocklet();
console.log('Blocklet script loaded successfully.');
// Now window.blocklet is available
console.log('Blocklet Name:', window.blocklet.appName);
} catch (error) {
console.error('Failed to load the blocklet script:', error);
}
}
// Run this function in a browser environment
initializeBlockletData();getPrefix()#
A convenience method to get the URL prefix for a blocklet. The prefix is the base path where the blocklet is served (e.g., / or /my-blocklet).
Parameters
Returns
Example
Get URL Prefix
// Assuming this runs on the client-side inside a blocklet
const prefix = sdk.blocklet.getPrefix();
console.log('Current blocklet prefix:', prefix);
// Or, you can pass a Blocklet object you've already fetched
async function logPrefixForRemoteBlocklet(url) {
const remoteBlocklet = await sdk.blocklet.getBlocklet(url);
const remotePrefix = sdk.blocklet.getPrefix(remoteBlocklet);
console.log(`Prefix for ${remoteBlocklet.appName} is:`, remotePrefix);
}
logPrefixForRemoteBlocklet('https://store.blocklet.dev');The Blocklet Object#
The getBlocklet() method returns a Blocklet object, which contains comprehensive metadata about the application. Below are some of the most commonly used properties.
Example Response
Blocklet Object Example
{
"did": "z8iZz...",
"appId": "z1s...",
"appName": "Blocklet Store",
"appDescription": "A marketplace for blocklets",
"appUrl": "https://store.blocklet.dev",
"prefix": "/",
"version": "1.16.29",
"isComponent": false,
"theme": {
"logo": "logo.png",
"colors": {
"primary": "#4F6AF6"
}
},
"navigation": [
{
"id": "home",
"title": "Home",
"link": "/"
}
],
"componentMountPoints": [],
"serverDid": "z2qaD...",
"webWalletUrl": "https://web.abtwallet.io"See all 1 lines
For a complete list of all properties, please refer to the Types reference page.
Next Steps#
Now that you know how to retrieve blocklet metadata, you might want to learn how to get information about its mounted components. Continue to the next section to learn about the ComponentService.