跳到內容

快速上手

本指南將帶你建立一個附有 連線錢包 按鈕的網頁來讀取使用者的 D9 帳戶。此方案同時支援 D9 錢包內建瀏覽器,以及透過 WalletConnect 存取的桌面端與行動端瀏覽器。

前置條件: 本機已安裝 Node.js 與 npm,手機端已安裝 D9 錢包。

終端機視窗
npm create vite@latest my-d9-dapp -- --template vanilla-ts
cd my-d9-dapp
npm install
npm install --save-exact @d9-network/dapp-connector@0.2.0 effect@4.0.5

新增 .env.local,填入主網端點中的主網設定:

終端機視窗
VITE_D9_RPC_URL=wss://rpc-hermes.d9network.com
VITE_D9_GENESIS_HASH=0xc3140da27f348abd94a638e9ca7ee7e9005caf5f2b451044c9487905ea5e0991
VITE_D9_RELAY_URL=wss://relay.d9network.com
VITE_D9_PROJECT_ID=d9-wallet-public
VITE_D9_WALLET_SCHEME=d9wallet

新增 src/config.ts 讀取並驗證這些變數:

function required(name: string): string {
const value = import.meta.env[name]?.trim();
if (!value) throw new Error(`缺少環境變數: ${name}`);
return value;
}
export const d9Config = {
rpcUrl: required("VITE_D9_RPC_URL"),
expectedGenesisHash: required("VITE_D9_GENESIS_HASH"),
relayUrl: required("VITE_D9_RELAY_URL"),
projectId: required("VITE_D9_PROJECT_ID"),
walletScheme: required("VITE_D9_WALLET_SCHEME"),
};

新增 src/wallet.ts。於應用程式根層級初始化一次,並在其他模組重複匯入使用:

import { ManagedRuntime } from "effect";
import { D9DAppConnector } from "@d9-network/dapp-connector";
import { d9Config } from "./config";
export const walletLayer = D9DAppConnector.layer({
dappName: "My D9 DApp",
walletConnect: {
projectId: d9Config.projectId,
relayUrl: d9Config.relayUrl,
metadata: {
name: "My D9 DApp",
description: "My D9 decentralized application",
url: window.location.origin,
icons: [`${window.location.origin}/icon.png`],
},
},
});
export const walletRuntime = ManagedRuntime.make(walletLayer);

新增 src/connect.ts。transport: "auto" 會在偵測到內建錢包時優先走注入通道,否則自動改用 WalletConnect:

import { Effect } from "effect";
import { D9DAppConnector } from "@d9-network/dapp-connector";
import { buildD9WalletConnectAppLink } from "@d9-network/dapp-connector/protocol";
import { d9Config } from "./config";
import { walletRuntime } from "./wallet";
export async function connectWallet(
showPairing: (qrUri: string, deepLink: string, cancel: () => Promise<void>) => void,
) {
return walletRuntime.runPromise(
Effect.gen(function* () {
const connector = yield* D9DAppConnector;
const start = yield* connector.connect({
transport: "auto",
requiredMethods: ["d9_signMessage", "d9_signTransaction"],
});
if (start.transport === "walletconnect") {
if (start.uri) {
const deepLink = buildD9WalletConnectAppLink(start.uri, d9Config.walletScheme);
showPairing(start.uri, deepLink, () => walletRuntime.runPromise(start.cancel));
}
yield* start.approval;
}
return yield* connector.getAccounts;
}),
);
}

取代 src/main.ts。請僅在使用者點擊事件中呼叫 connectWallet,瀏覽器與行動錢包皆要求由明確的使用者操作觸發喚起。

import { connectWallet } from "./connect";
const app = document.querySelector<HTMLDivElement>("#app")!;
const button = document.createElement("button");
const status = document.createElement("p");
const qrContainer = document.createElement("div");
button.textContent = "連線錢包";
app.replaceChildren(button, status, qrContainer);
function renderPairingQr(qrUri: string, container: HTMLElement) {
// 串接你使用的 QR Code 函式庫(例如 qrcode.toCanvas)渲染 qrUri。
// 切勿在正式環境將配對 URI 寫入日誌或回報分析平台。
container.textContent = "請使用 QR Code 函式庫渲染 WalletConnect 配對碼";
void qrUri;
}
button.addEventListener("click", async () => {
try {
const accounts = await connectWallet((qrUri, deepLink, cancel) => {
renderPairingQr(qrUri, qrContainer);
const link = document.createElement("a");
link.href = deepLink;
link.textContent = "開啟 D9 錢包";
const cancelBtn = document.createElement("button");
cancelBtn.textContent = "取消";
cancelBtn.onclick = () => void cancel();
status.replaceChildren(link, " ", cancelBtn);
});
qrContainer.replaceChildren();
status.textContent = accounts.map((account) => account.address).join(", ");
} catch (error) {
qrContainer.replaceChildren();
status.textContent = String(error);
}
});
  1. 執行 npm run dev,在桌面瀏覽器開啟頁面並點擊 連線錢包。
  2. 使用任意 QR Code 函式庫(如 qrcode)將 qrUri 渲染為 QR Code 並以 D9 錢包掃描(切勿將配對 URI 寫入日誌或分析平台)。
  3. 在錢包中確認授權,頁面即會顯示已授權的 SS58 位址。

在手機瀏覽器中可直接點擊 開啟 D9 錢包 喚起應用程式;在 D9 錢包內建瀏覽器中則會直接彈出授權提示。如遇問題,請參閱問題排查。

若不想使用 transport: "auto",可將 src/connect.ts 中 Effect.gen 的函式主體替換為以下任一實作。

僅使用內建瀏覽器(注入式 PAPI):

const connector = yield* D9DAppConnector;
const isAvailable = yield* connector.papi.isAvailable;
if (!isAvailable) {
throw new Error("未偵測到 D9 錢包內建提供者");
}
yield* connector.papi.connect();
return yield* connector.getAccounts;

僅使用 WalletConnect(外部瀏覽器):

const connector = yield* D9DAppConnector;
const start = yield* connector.walletConnect.connect({
requiredMethods: ["d9_signMessage", "d9_signTransaction"],
});
if (start.uri) {
const deepLink = buildD9WalletConnectAppLink(start.uri, d9Config.walletScheme);
showPairing(start.uri, deepLink, () => walletRuntime.runPromise(start.cancel));
}
yield* start.approval;
return yield* connector.getAccounts;

當使用者關閉 QR Code 視窗或主動取消時,請呼叫 showPairing 收到的 cancel 回呼函式。

驗證: 頁面正常顯示 SS58 位址。若顯示 未偵測到 D9 錢包內建提供者,代表目前未運行於 D9 錢包內建瀏覽器中,請改用 WalletConnect 通道。