Connector API
在應用程式根層級初始化一次錢包連接器,即可在整個應用程式中重複使用,用於連線錢包、讀取已授權帳戶以及監聽狀態變化。
前置條件: 已安裝 @d9-network/dapp-connector@0.2.0 與 effect@4.0.5(參閱 SDK 套件)。
1. 建立連接器
Section titled “1. 建立連接器”新增 src/connector.ts,為整個應用程式建立單一實例的 Layer:
import { D9DAppConnector } from "@d9-network/dapp-connector";import { d9Config } from "./config";
export const connectorOptions = { dappName: "My D9 DApp", walletConnect: { projectId: d9Config.projectId, relayUrl: d9Config.relayUrl, metadata: { name: "My D9 DApp", description: "My decentralized application", url: window.location.origin, icons: [`${window.location.origin}/icon.png`], }, },};
export const connectorLayer = D9DAppConnector.layer(connectorOptions);2. 連線錢包並讀取帳戶
Section titled “2. 連線錢包並讀取帳戶”import { Effect } from "effect";import { D9DAppConnector } from "@d9-network/dapp-connector";
export const connectProgram = Effect.gen(function* () { const connector = yield* D9DAppConnector; const start = yield* connector.connect({ transport: "auto" });
if (start.transport === "walletconnect") { // 等待核准前,先將 start.uri 渲染為 QR Code 或行動裝置深連結 yield* start.approval; }
return yield* connector.getAccounts;});start.approval、start.cancel、start.response、connector.snapshot 與 connector.getAccounts 皆為 Effect 物件,請使用 yield* 而非 await。
請使用以 connectorLayer 建立的執行環境(例如 快速上手 中的 walletRuntime)來執行第 2 步與第 3 步的程式。
驗證: getAccounts 回傳使用者已授權的帳戶清單。
3. 監聽連線狀態變化
Section titled “3. 監聽連線狀態變化”connector.changes 是一個 Effect Stream,訂閱後會立即推送目前快照:
import { Effect, Stream } from "effect";import { D9DAppConnector } from "@d9-network/dapp-connector";
export const watchConnectionProgram = Effect.gen(function* () { const connector = yield* D9DAppConnector; yield* Stream.runForEach(connector.changes, (snapshot) => Effect.logInfo(`錢包狀態: ${snapshot.status} (${snapshot.transport})`), );});4. 在行動裝置上開啟 D9 錢包
Section titled “4. 在行動裝置上開啟 D9 錢包”將 WalletConnect 配對 URI 與錢包 URL scheme 傳入 /protocol 匯出的 buildD9WalletConnectAppLink:
import { buildD9WalletConnectAppLink } from "@d9-network/dapp-connector/protocol";
const deepLink = buildD9WalletConnectAppLink(start.uri, d9Config.walletScheme);完整實作請參閱 瀏覽器錢包連線。
不使用 Effect:/web 封裝介面
Section titled “不使用 Effect:/web 封裝介面”在 React、Vue 或原生 JavaScript/TypeScript 專案中,可直接呼叫基於 Promise 的 /web 介面,並傳入相同的 connectorOptions:
import { createWebD9Connector } from "@d9-network/dapp-connector/web";import { connectorOptions } from "./connector";
export const webConnector = createWebD9Connector(connectorOptions);
// 同步讀取目前狀態const accounts = webConnector.getAccounts();const snapshot = webConnector.getSnapshot();
// 訂閱狀態變化const unsubscribe = webConnector.subscribe((nextSnapshot) => { console.log("狀態已更新:", nextSnapshot.status);});
// 中斷目前工作階段,或永久關閉連接器await webConnector.disconnect();await webConnector.close();/protocol 匯出項目
Section titled “/protocol 匯出項目”/protocol 進入點僅包含純資料輔助工具與 Schema 定義,不會引入任何通道 SDK 依賴:
| 匯出項目 | 用途 |
|---|---|
serializeD9SiwxMessage |
產生標準 CAIP-122 登入訊息字串 |
D9AuthenticateParamsSchema |
解碼並驗證登入 Challenge(Effect Schema) |
D9_WALLET_CONNECT_CHAIN_ID |
常數 d9net:000000000000000000000000000000d9 |
