DogeOS SDK 软件

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

快速启动 • 妇女 API 参考 • 妇女 开发者控制台

安装

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

npm install @dogeos/dogeos-sdk wagmi

pnpm add @dogeos/dogeos-sdk wagmi

获取客户身份

在 开发者控制台 并把它的客户身份复制到您的应用程序中。 一个项目有单独的Sandbox和Live客户端ID.

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

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

连接钱包

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

"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 设置指南 用于布局示例.

读取连接的账户

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

"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() 访问连接的钱包的其他链条提供者。 见 账户动作和签名示例。 。 。 .

钱包连接或签名本身并不为您的后端创建认证的会话 。 对于基于钱包的签名, 请在创建会话前先有您的服务器问题并验证新的挑战 。 跟着 登录指南。 。 。 .

连接和准备

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

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

MyDoge内部,SDK自动选择本地钱包. 保留正常的提供者配置和连接按钮 。 在嵌入式钱包被禁用时可以连接本地钱包或外部钱包, 因此不需要 isWalletReady 用于所有钱包动作。 见 本地钱包连接。 。 。 .

在 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 正在运行的地方, 并给你一个连接电话, 返回两个位置的账户 :

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。 。 。 .

见 配置 实例,包括 DogeOS 奇基奇测试网。 。 。 .

钱包连接

要启用钱包连接, 请在 重下仪表板 并通过项目ID。 它与您的 DogeOS 客户端ID 分开 .

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 当钱包流动属于页面而不是模式时,在您现有的提供者内部.

"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 围绕一个嵌入。 配置它,以免它接管页面的主连接:

"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.

"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秒内忽略了第二个链接.

文档

• 快速启动 用于安装和供应商设置.
• 配置 用于链条、登录选项和主题.
• 核心工作流程 用于签名、网络更改和提供者请求.
• 嵌入式钱包 用于内置UI和本地MyDoge行为.
• 瓦格米融合 对于已经使用Wagmi钩子的应用程序.
• API 参考 用于组件、钩子和帮助者.
• 解决问题 用于连接错误和浏览器要求.