# @dogeos/dogeos-sdk 中文文档

规范地址：https://npmcn.com/package/%40dogeos/dogeos-sdk/

版本：4\.1\.0
npm 元数据更新时间：2026-11-12T16:05:39.108Z
中文译文更新时间：2026-11-12T16:07:08.533Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dogeos/dogeos-sdk
原文对照：https://npmcn.com/package/%40dogeos/dogeos-sdk/?lang=original
项目主页：https://sdk.dogeos.com/

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.9 MB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：29 个
- peer 依赖：react \>=18，wagmi \>=2\.0\.0，react-dom \>=18
- 首次发布：2025-09-16T02:58:50.883Z
- 最新版本发布：2026-11-12T16:05:38.795Z
- 近 30 天下载量：6716（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：108（近 12 个月 97 个）

## 中文简介

连接您的 React app 到 DogeOS 钱包 。 让用户用电子邮件,Google或X签名,连接一个外部钱包,并在 MyDoge dApp 浏览器内使用他们的 MyDoge 钱包.

## 安装

```sh
npm install @dogeos/dogeos-sdk
```

也可以使用：`pnpm add @dogeos/dogeos-sdk`、`yarn add @dogeos/dogeos-sdk`、`bun add @dogeos/dogeos-sdk`

## README

# DogeOS SDK 软件

连接您的 React app 到 DogeOS 钱包 。 让用户用电子邮件,Google或X签名,连接一个外部钱包,并在 MyDoge dApp 浏览器内使用他们的 MyDoge 钱包.

[快速启动](https://docs.dogeos.com/en/sdk) • 妇女 [API 参考](https://docs.dogeos.com/en/sdk/api/hooks) • 妇女 [开发者控制台](https://console.dogeos.com/)

## 安装

使用回放 18 或后回放 DOM 18 或后回放. 安装 `wagmi`,需要的同伴依赖,即使您只使用 SDK 钩. 支持类型脚本 .

```bash
npm install @dogeos/dogeos-sdk wagmi
```

```bash
pnpm add @dogeos/dogeos-sdk wagmi
```

## 获取客户身份

在 [开发者控制台](https://console.dogeos.com/) 并把它的客户身份复制到您的应用程序中。 一个项目有单独的Sandbox和Live客户端ID.

开发期间使用 Sandbox 客户端ID 。 您的项目概况显示是否从 `localhost` 财务报告和审定财务报表 `127.0.0.1` 准备好了 在从这些域连接之前, 将您主机应用程序源添加到匹配环境 。 来源包括方案、主机名和端口,例如 `https://app.example.com`。 。 。 .

您的客户端 ID 是公开的, 属于浏览器捆绑 。 您的应用程序需要一个客户端ID来配置 SDK .

## 连接钱包

包装您的应用程序 `WalletConnectProvider` 并导入样式表一次。 提供者下方的部件可以使用SDK钩.

```tsx
"use client";

import {
  WalletConnectProvider,
  useAccount,
  useWalletConnect,
  type WalletConnectKitConfig,
} from "@dogeos/dogeos-sdk";
import "@dogeos/dogeos-sdk/style.css";

const config: WalletConnectKitConfig = {
  clientId: "YOUR_DOGEOS_CLIENT_ID",
};

function WalletButton() {
  const { openModal, isConnected, isConnecting, error } = useWalletConnect();
  const { address } = useAccount();

  return (
    <div>
      <button type="button" disabled={isConnecting} onClick={openModal}>
        {isConnecting ? "Connecting..." : isConnected ? address : "Connect wallet"}
      </button>
      {error ? <p role="alert">{error}</p> : null}
    </div>
  );
}

export default function App() {
  return (
    <WalletConnectProvider config={config}>
      <WalletButton />
    </WalletConnectProvider>
  );
}
```

样式表只给SDK UI样式:模式、土司和 `WalletConnectEmbed`您的页面保留了自己的重置、字体和颜色。 如果您不包含导入, 提供者在挂载时会添加相同的样式表 。 它将其样式表添加为已构建的样式表, 该样式表是一个内容安全政策, 没有 `'unsafe-inline'` 内 `style-src` 允许。 没有构建样式表的浏览器( 在Safari 16.4) 获得 `<style>` 要素,此类政策块 `style.css` 覆盖样式表,但不能 `config.theme` 颜色 要重塑 SDK UI, 目标元素在内 `.dogeos-sdk`。 。 。 .

`openModal()` 打开连接流。 一旦连接,它就会打开账户视图. 使用 `disconnect()` 从 `useWalletConnect()` 来断开活动钱包.

在"Next.js App Router"中,将提供者放入客户端组件,如上. 见 [Next.js 设置指南](https://docs.dogeos.com/en/sdk#nextjs) 用于布局示例.

## 读取连接的账户

`useAccount()` 曝光活动地址、链条、钱包和提供者.

```tsx
"use client";

import { useAccount, useWalletConnect } from "@dogeos/dogeos-sdk";

export function AccountDetails() {
  const { isConnected } = useWalletConnect();
  const { address, chainType, chainId } = useAccount();

  if (!isConnected) return <p>Connect a wallet to continue.</p>;

  return (
    <div>
      <p>{address}</p>
      <p>{chainType}: {chainId}</p>
    </div>
  );
}
```

同样的钩子提供 `switchChain()`, (中文(简体) ), `signMessage()` 财务报告和审定财务报表 `signInWithWallet()`启用 `currentProvider` 用于特定链式请求,或 `useConnectors()` 访问连接的钱包的其他链条提供者。 见 [账户动作和签名示例](https://docs.dogeos.com/en/sdk/guides)。 。 。 .

钱包连接或签名本身并不为您的后端创建认证的会话 。 对于基于钱包的签名, 请在创建会话前先有您的服务器问题并验证新的挑战 。 跟着 [登录指南](https://docs.dogeos.com/en/sdk/guides#sign-in-with-wallet)。 。 。 .

## 连接和准备

使用匹配您的应用程序需要的状态 .

| 外地 | 含义 |
| --- | --- |
| `isConnected` | 钱包已连接 。 与当前账户和提供者一起用于钱包动作 . |
| `isConnecting` | 钱包连接尝试正在进行中 . |
| `connectionStatus` | `disconnected`, (中文(简体) ), `connecting` 或者说 `connected`。 。 。 . |
| `walletStatus` | 嵌入式钱包状态 : `disabled`, (中文(简体) ), `initializing`, (中文(简体) ), `ready`, (中文(简体) ), `unavailable` 或者说 `error`。 。 。 . |
| `isWalletReady` | 嵌入式钱包准备接受登录. |

`WalletConnectProvider` 让你的应用 直接离开我的道格。 在Android in-app浏览器(一个WebView)中,嵌入式钱包,加上电子邮件或社交签名的配置也恢复了已保存的连接,等待页面完成加载,最多5秒,然后开始: MyDoge的in-app浏览器仍然可以识别自己,直到那时. `walletStatus` 报告 `initializing` 同时 在 MyDoge 内, 提供者显示一个简短的“ 准备钱包连接... ” 状态, 在本地钱包准备好时取代您的应用程序, 如果需要超过5秒, 则使用重试按钮 。 在一些更古老的Android设备上 MyDoge识别自己很晚,因此您的应用程序可以一次在浏览器模式下渲染,然后在本地模式下再次上载.

MyDoge内部,SDK自动选择本地钱包. 保留正常的提供者配置和连接按钮 。 在嵌入式钱包被禁用时可以连接本地钱包或外部钱包, 因此不需要 `isWalletReady` 用于所有钱包动作。 见 [本地钱包连接](https://docs.dogeos.com/en/sdk/embedded-wallets#native-first-connection-in-mydoge)。 。 。 .

## 在 MyDoge 应用程序内

在 MyDoge 的 dApp 浏览器中,本地的应用程序回答了每一个钱包请求,而SDK 则没有显示它自己的钱包UI,也没有打开弹出. 同一代码在浏览器和MyDoge中工作:

-   `openModal()` 请求 MyDoge 连接 。 当钱包已连接时, 它打开 MyDoge 的账户表 在 MyDoge 上构建支持它; 在没有它的情况下构建它, 包括3.1.1 (Building 652) 以及更早时, 它什么都不做, 登录一个警告, 所以给用户一个断开连接按钮, 如果您支持多个网络, a `switchChain()` 控制系统.
-   `WalletConnectEmbed` 显示一个带有连接、账户和断开按钮的小型 MyDoge 卡片,而不是钱包列表。 它的账户按钮需要同样的账户表支持.
-   第一次访问不会在页面加载时提示 。 一个已保存的连接被恢复,而 MyDoge 构建此支持,它也会重新连接一个已经批准的用户的dApp;否则SDK会等待用户来窃听连接.
-   `disconnect()` 还撤销了DApp在"MyDoge"中的批准.
-   DogeOS 电子邮件和社会登录(`useDogeOSAuth().login()`拒绝 `DogeOSHostError`启用 `signInWithWallet()` 并验证服务器上的签名.

`useWalletHost()` 告诉你 dApp 正在运行的地方, 并给你一个连接电话, 返回两个位置的账户 :

```tsx
import { isWalletError, useWalletHost, WalletErrorCode } from "@dogeos/dogeos-sdk";

function ConnectButton() {
  const { isNativeHost, connect } = useWalletHost();

  const onClick = async () => {
    try {
      const { address } = await connect();
      console.log("Connected", address);
    } catch (error) {
      if (isWalletError(error, WalletErrorCode.UserRejected)) return;
      throw error;
    }
  };

  return <button type="button" onClick={onClick}>{isNativeHost ? "Connect MyDoge" : "Connect wallet"}</button>;
}
```

## 配置您的应用程序

通过可选设置 `clientId` 内 `WalletConnectKitConfig`。 。 。 .

| 选项 | 用它来 |
| --- | --- |
| `chains` | 选择支持的网络, 按链条家族分组 . |
| `defaultConnectChain` | 选择初始链条家族, 例如 `"evm"`。 。 。 . |
| `login` | 选择哪个电子邮件、社会和外部钱包选项 . |
| `metadata` | 设置您的应用程序的名称、 描述、 URL 和图标 . |
| `theme` | 设置颜色和光或暗模式. |
| `walletConnectProjectId` | 启用钱包连接 . |
| `connectors` | 自定义钱包列表 `getConnectors()`。 。 。 . |

见 [配置](https://docs.dogeos.com/en/sdk/configuration) 实例,包括 [DogeOS 奇基奇测试网](https://docs.dogeos.com/en/sdk/configuration#chains)。 。 。 .

### 钱包连接

要启用钱包连接, 请在 [重下仪表板](https://dashboard.reown.com/) 并通过项目ID。 它与您的 DogeOS 客户端ID 分开 .

```tsx
import type { WalletConnectKitConfig } from "@dogeos/dogeos-sdk";

const config: WalletConnectKitConfig = {
  clientId: "YOUR_DOGEOS_CLIENT_ID",
  walletConnectProjectId: "YOUR_WALLETCONNECT_PROJECT_ID",
  metadata: {
    name: "My DogeOS app",
    description: "My DogeOS application",
    url: "https://app.example.com",
    icons: ["https://app.example.com/icon.png"],
  },
};
```

无 `walletConnectProjectId`钱包是隐藏的 电子邮件、社会登录和支持的注射钱包仍然可用。 如果您使用其来源许可列表, 请将您的应用程序的出处添加到您的 Reown 工程中 .

## 将钱包内嵌

使用 `WalletConnectEmbed` 当钱包流动属于页面而不是模式时,在您现有的提供者内部.

```tsx
"use client";

import { WalletConnectEmbed } from "@dogeos/dogeos-sdk";

export function WalletPanel() {
  return <WalletConnectEmbed style={{ width: "100%", maxWidth: 448 }} />;
}
```

`WalletConnectEmbed` 并取出这些道具:

-   `initialView`:它开始和返回的拾取器, `"walletList"` 或者说 `"walletSearch"`。默认情况如下: `config.login`。 。 。 .
-   `hideHeader`: 将起始视图的标题从外出,用于一个让嵌入其自己标题的页面. 该行的控件,例如钱包列表的链接,留下. 后出观有取名.
-   `keepPickerAfterConnect`:在钱包连接后将取取器保留在屏幕上,而不是显示账户视图. 连接另一个钱包,其错误和安装指南仍然显示 .

在MyDoge里面嵌入的总是MyDoge卡,不管这些道具怎么说.

## 链接第二个钱包

让一个登录的用户证明他们拥有另一个钱包,比如将钱包与他们的账户连接起来,让第二个 `WalletConnectProvider` 围绕一个嵌入。 配置它,以免它接管页面的主连接:

```tsx
"use client";

import { WalletConnectEmbed, WalletConnectProvider, type WalletConnectKitConfig } from "@dogeos/dogeos-sdk";

const linkConfig: WalletConnectKitConfig = {
  clientId: process.env.NEXT_PUBLIC_DOGEOS_CLIENT_ID!,
  login: { basicLogins: ["externalWallets"], socialLogins: [] },
  // Connect only when the user picks a wallet, and save nothing.
  autoRestore: false,
  persistConnection: false,
  // Ask an EVM wallet to show its account picker even for a site it already approved.
  forceAccountSelection: { blockedAddresses: alreadyLinkedAddresses },
};

export function LinkWallet() {
  return (
    <WalletConnectProvider config={linkConfig}>
      <WalletConnectEmbed initialView="walletSearch" hideHeader keepPickerAfterConnect />
    </WalletConnectProvider>
  );
}
```

-   `autoRestore: false` 跳过在装入时恢复已保存的连接, 在 MyDoge 中, 静态重接也 。 它不覆盖DogeOS的登录:在用户签名的页面上,一个提供社交登录的提供者在负载上连接他们的社交钱包. 这个 `login` 上行保留外部钱包的链接提供者,这样就不会发生.
-   `persistConnection: false` 保存不重联提示,并留下主提供者的独处.
-   `forceAccountSelection` 适用于 EVM 浏览器钱包; MyDoge 和嵌入式钱包忽略了它。 在连接之前,它再次向钱包询问网站的账户权限(EIP-2255),这使得大多数钱包显示其取取取器. 如果钱包不支持此请求并返回其中之一 `blockedAddresses`,连接失败,因为有信件要求用户断开钱包中的站点. `revokePermissions: true` 对跳过拾取器的钱包, 权限是每个站点的,这样也可以断开与页面上同一钱包的主连接.

请求连接的钱包签名以证明所有权, 并在您的服务器上检查 .

## 链接到 MyDoge 内的另一个 dApp

在 MyDoge 的在线浏览器中, 一个平面 `https` 链接到您 dApp 浏览器会话中的另一个 dApp 负载。 钱包仍然绑定在您 dApp 的出处, 所以另一个 dApp 无法连接 。 与它连接 `mydoge://dapp` URL取而代之:MyDoge然后用自己的钱包会话打开目标作为自己的dApp. 用户看到目标的细节屏幕和相接器 **打开**你的DAP在那时才会关闭.

`isInMyDogeBrowser()` 通过它的 EIP-6963 通知(rdns) 检测 MyDoge 的内应用浏览器 `com.mydoge.wallet`) (中文(简体) ). 它决定 `false` 在超时(默认为500ms后)和服务器渲染期间. `getDappHref()` 返回时 `mydoge://dapp` 链接到 MyDoge 和其它任何地方的平地 URL.

```tsx
"use client";

import { useEffect, useState } from "react";
import { getDappHref, isInMyDogeBrowser } from "@dogeos/dogeos-sdk";

const BUY_MOON_URL = "https://muchfi.example/buy?token=MOON";

export function BuyMoonLink() {
  // null until detection finishes, so no plain link can be tapped inside MyDoge first.
  const [inMyDoge, setInMyDoge] = useState<boolean | null>(null);

  useEffect(() => {
    void isInMyDogeBrowser().then(setInMyDoge);
  }, []);

  const href = inMyDoge === null ? undefined : getDappHref(BUY_MOON_URL, { inMyDoge });
  return <a href={href}>Buy MOON</a>;
}
```

离开链接没有 `href` 直到检测结束 在您的页面水合物之前, 可以在 MyDoge 内调取一个服务器上的纯链接, 它将在您 dApp 的会话中装入目标 。 在MyDoge外,水分化后检测需要高达500ms.

`getMyDogeDappLink(targetUrl)` 直接构建链接 : `mydoge://dapp?url=` 之后是完整的目标 URL,一次编码为 `encodeURIComponent`。通过原始 `https` URL,不是已经编码的 。 它首先使URL正常化,因为浏览器会(例如,一个空间会变成 `%20`),因为MyDoge拒绝原始空间和相类似的字符. 它扔一个 `TypeError` 绝对值以外的任何 `https` URL,用于一个有用户名或密码的URL,以及一个超过MyDoge 8 KiB限制的URL. `getDappHref()` 在每个浏览器中应用相同的检查,因此一个糟糕的URL在普通测试中出现.

这些规则来自MyDoge的 dApp 深度链接合作伙伴指南:

-   **在水龙头前放水龙头.** 检测 MyDoge 先将链接放入用户自带的元素中. 一个简单的链接, a `target="_blank"` 链接,或 `window.open` 在水龙头处理器中被称为同步工作。 设置 `location.href` iOS不起作用, 导航后 `await` 或者一个计时器可能被屏蔽.
-   **只有顶级的页面工作.** 一个iframe内部的链接在iOS上被忽略,在Android上可能被忽略.
-   **目标必须在 MyDoge 中列出.** 它的出处必须与目的地dApp公布的CMS完全一致 `projectLink` 源代码。 子域类 `www` 而非默认端口则算作不同来源。 路径、查询和片段没有变化.
-   **MyDoge 3.1.1(建造652所)或以后需要.** 之前的建筑忽略了窃听器 `mydoge://` 链接,所以没有发生。 他们也这样宣布 `com.mydoge.wallet` 提供者,所以一个页面不能告诉他们 除了652.
-   MyDoge在2秒内忽略了第二个链接.

## 文档

-   [快速启动](https://docs.dogeos.com/en/sdk) 用于安装和供应商设置.
-   [配置](https://docs.dogeos.com/en/sdk/configuration) 用于链条、登录选项和主题.
-   [核心工作流程](https://docs.dogeos.com/en/sdk/guides) 用于签名、网络更改和提供者请求.
-   [嵌入式钱包](https://docs.dogeos.com/en/sdk/embedded-wallets) 用于内置UI和本地MyDoge行为.
-   [瓦格米融合](https://docs.dogeos.com/en/sdk/wagmi) 对于已经使用Wagmi钩子的应用程序.
-   [API 参考](https://docs.dogeos.com/en/sdk/api/hooks) 用于组件、钩子和帮助者.
-   [解决问题](https://docs.dogeos.com/en/sdk/troubleshooting) 用于连接错误和浏览器要求.

## 常见问题

### @dogeos/dogeos-sdk 是什么？

连接您的 React app 到 DogeOS 钱包 。 让用户用电子邮件,Google或X签名,连接一个外部钱包,并在 MyDoge dApp 浏览器内使用他们的 MyDoge 钱包\.

### 如何安装 @dogeos/dogeos-sdk？

在项目目录运行 npm install @dogeos/dogeos-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18）、wagmi（\>=2\.0\.0）、react-dom（\>=18）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @dogeos/dogeos-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @dogeos/dogeos-sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @dogeos/dogeos-sdk 可以商用吗？

@dogeos/dogeos-sdk 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @dogeos/dogeos-sdk 的下载量有多少？

根据 npm 官方下载统计，@dogeos/dogeos-sdk 在 2026/10/13 – 2026/11/11 这 30 天内被下载 6,716 次，日均约 224 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dogeos/dogeos-sdk 还在维护吗？

最新版本 4\.1\.0 发布于 2026/11/13（今天）；至今共发布 108 个版本，其中过去 12 个月发布了 97 个；首次发布于 2025/09/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。