BlockletServiceは、ブロックレットのメタデータにアクセスするためのメソッドを提供します。Blockletオブジェクトで表されるこのメタデータには、アプリケーション名、URLプレフィックス、バージョン、コンポーネントのマウントポイントなどの重要な情報が含まれています。
このサービスは、主に2つの方法でこの情報を取得できます。
クライアントサイド:
ブロックレットのフロントエンド内でコードが実行されているときに自動的に利用可能になるグローバルな
window.blockletオブジェクトを読み取ることによって。リモートフェッチ:
指定されたベースURLからブロックレットのメタデータを取得することによって。これは、サーバーサイドのコンテキストや、外部アプリケーションからブロックレットと対話する場合に便利です。
パフォーマンスを向上させるため、このサービスはリモートで取得したブロックレットデータに対して60秒間持続するインメモリキャッシュを実装しています。
メソッド
getBlocklet()
ブロックレットのメタデータオブジェクトを取得します。このメソッドの動作は、提供された引数によって変わります。
- クライアントサイドで引数なしで呼び出されると、同期的に
window.blockletを返します。 baseUrlを指定して呼び出されると、リモートURLから非同期でメタデータを取得します。
パラメータ
- baseUrl
string— メタデータを取得するブロックレットのベースURL。サーバーサイドでの使用に必要です。 - force
boolean(default:false) — trueの場合、キャッシュをバイパスしてリモートURLから新しいデータを取得します。
戻り値
- Promise | Blocklet
Promise<Blocklet> | Blocklet— リモートで取得する場合はブロックレットのメタデータオブジェクトで解決されるPromiseを返し、クライアントサイドのコンテキストではオブジェクトを直接返します。
例
クライアントサイドでBlockletを取得
// このコードは、ブロックレットのフロントエンド環境で実行されていることを前提としています
async function logBlockletName() {
try {
// クライアントでは、データがプリロードされている場合、getBlocklet()は同期的になることがあります
const blocklet = await sdk.blocklet.getBlocklet();
console.log('Blocklet名:', blocklet.appName);
} catch (error) {
console.error('ブロックレット情報の取得に失敗しました:', error);
}
}
logBlockletName();URLからBlockletを取得
async function fetchRemoteBlocklet(url) {
try {
console.log(`${url}からブロックレット情報を取得中...`);
const blocklet = await sdk.blocklet.getBlocklet(url);
console.log(`正常に取得しました: ${blocklet.appName} v${blocklet.version}`);
// 再度取得します。今回はキャッシュから取得されるはずです
const cachedBlocklet = await sdk.blocklet.getBlocklet(url);
console.log('キャッシュから取得:', cachedBlocklet.appName);
// キャッシュをバイパスして強制的に再取得します
const freshBlocklet = await sdk.blocklet.getBlocklet(url, true);
console.log('強制再取得:', freshBlocklet.appName);
} catch (error) {
console.error('リモートブロックレットの取得に失敗しました:', error);
}
}
fetchRemoteBlocklet('https://store.blocklet.dev');loadBlocklet()
これは、__blocklet__.jsスクリプトをドキュメントの<head>に動的に挿入するクライアントサイドのユーティリティメソッドです。このスクリプトはwindow.blockletオブジェクトを生成し、メタデータをグローバルに利用可能にします。これは、ブロックレット自体ではないが、ブロックレットと対話する必要があるアプリケーションに特に便利です。
注: このメソッドはサーバーサイド(Node.js)環境で呼び出されると失敗します。
戻り値
- Promise
Promise<void>— スクリプトが正常にロードされたときに解決され、エラーがある場合は拒否されるPromise。
例
Blockletスクリプトを動的にロード
async function initializeBlockletData() {
try {
await sdk.blocklet.loadBlocklet();
console.log('Blockletスクリプトが正常にロードされました。');
// これでwindow.blockletが利用可能になります
console.log('Blocklet名:', window.blocklet.appName);
} catch (error) {
console.error('ブロックレットスクリプトのロードに失敗しました:', error);
}
}
// この関数はブラウザ環境で実行してください
initializeBlockletData();getPrefix()
ブロックレットのURLプレフィックスを取得するための便利なメソッドです。プレフィックスは、ブロックレットが提供されるベースパスです(例:/ または /my-blocklet)。
パラメータ
- blocklet
Blocklet— オプションのBlockletオブジェクト。指定された場合、そのprefixプロパティが返されます。
戻り値
- string | null
string | null— 文字列のプレフィックス(例:'/app')またはデフォルトとして'/'。windowが利用できず、blockletオブジェクトが渡されないサーバーサイド環境では、nullを返します。
例
URLプレフィックスを取得
// これがブロックレット内のクライアントサイドで実行されることを想定しています
const prefix = sdk.blocklet.getPrefix();
console.log('現在のブロックレットのプレフィックス:', prefix);
// または、すでに取得したBlockletオブジェクトを渡すこともできます
async function logPrefixForRemoteBlocklet(url) {
const remoteBlocklet = await sdk.blocklet.getBlocklet(url);
const remotePrefix = sdk.blocklet.getPrefix(remoteBlocklet);
console.log(`${remoteBlocklet.appName}のプレフィックスは:`, remotePrefix);
}
logPrefixForRemoteBlocklet('https://store.blocklet.dev');Blockletオブジェクト
getBlocklet()メソッドは、アプリケーションに関する包括的なメタデータを含むBlockletオブジェクトを返します。以下は、最も一般的に使用されるプロパティの一部です。
- did
string— ブロックレットの分散型識別子(DID)。 - appName
string— アプリケーションの人間が読める名前。 - appUrl
string— アプリケーションの完全な公開URL。 - prefix
string— ブロックレットがマウントされているURLプレフィックス。 - version
string— ブロックレットのバージョン(例:'1.2.3')。 - isComponent
boolean— ブロックレットがコンポーネントであるかどうかを示します。 - componentMountPoints
BlockletComponent[]— このブロックレットによってマウントされたコンポーネントの配列。 - theme
BlockletTheme— 色やロゴなどのテーマ設定を含むオブジェクト。 - navigation
BlockletNavigation[]— ブロックレットのUI用のナビゲーション項目の配列。 - serverDid
string— ブロックレットを実行しているBlocklet ServerインスタンスのDID。
レスポンス例
Blockletオブジェクトの例
{
"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"
}すべてのプロパティの完全なリストについては、Typesのリファレンスページを参照してください。
次のステップ
ブロックレットのメタデータを取得する方法を学んだので、次はマウントされたコンポーネントに関する情報を取得する方法を学びたいと思うかもしれません。次のセクションに進み、ComponentServiceについて学びましょう。