介绍

此文档用户帮助 DApp 开发者接入 imToken DApp SDK。

一般情况下，DApp 需要一个宿主环境和用户的钱包进行交互, 和 metamask 一样 imToken 在 app 中 提供了这个环境.

在 DApp browser 中, DApp 能够做和 metamask 中一样并且更多的事情。

Provider

imToken 目前支持 Ethereum 和 EOS 的 DApp。

DApp browser 兼容 Metamask, 你可以直接把你的 Ethereum DApp 迁移到 imToken， 甚至不用写任何代码。

DApp browser 同时兼容 Scatter, 你可以基于 Scatter 开发 EOS DApp，并运行在 imToken 中。

⚠️ 注意: 对于 Scatter-js, 目前我们只支持 `scatterjs-core` 小于等于 2.3.8 的版本。

DApp browser  和 DApp 的交互基于 EIP1102 的标准，DApp 必须按照 EIP1102 的方式才可以拿到用户帐号、和执行其他操作。

⚠️ DApp browser 不会往浏览器环境中注入 web3， 只注入一个基本的 `provider`， DApp 需要这样调用：

👉 你也可以检查 metamask 的相关 文档

window.addEventListener("load", async () => {
  // Modern dapp browsers...
  if (window.ethereum) {
    window.web3 = new Web3(ethereum);
    try {
      // Request account access if needed
      await ethereum.enable();
      // Acccounts now exposed
      web3.eth.sendTransaction({
        /* ... */
      });
    } catch (error) {
      // User denied account access...
    }
  }
  // Legacy dapp browsers...
  else if (window.web3) {
    window.web3 = new Web3(web3.currentProvider);
    // Acccounts always exposed
    web3.eth.sendTransaction({
      /* ... */
    });
  }
});

检测是否是 imToken

你可以通过 !!window.imToken 或者 window.ethereum.isImToken 来检测当前浏览器环境是否是 imToken DApp browser, 如果返回 true 表示当前是 imToken 环境

callAPI

我们提供了一系列的方法来增强 DApp 的功能，每一个方法都有一个 apiName, 开发者可以按下面的形式调用:

imToken.callAPI(apiName, options, callback)

Params	Type	Description
apiName	string	被调用方法的名称，在后面会看到可用的方法名列表
options	object	方法参数，取决于具体的方法
callback	function	方法的回调函数

回调函数的风格和 NodeJS 一样，第一个参数总是 error 对象 （如果没有错误发生，error 的值会是 null）, error 对象总是会包含一个 message 属性, 有时候会包含一个 code 属性表示特殊的错误码 。 第二个参数是方法调用成功返回的 result。

callAPI

imToken.callAPI(apiName, params, (error, result) => {
  if (error) {
    alert(error.message);
  } else {
    alert(result);
  }
});

和 callAPI 一样， 你也可以通过 callPromisifyAPI 去调用一个 API, 如果你需要一个 Promise 风格的接口的话：

callPromisifyAPI

imToken
  .callPromisifyAPI(apiName, params)
  .then((result) => alert(result))
  .catch((error) => {
    alert(error.message);
  });

API

transaction

web3.eth.sendTransaction

关于交易发送，请参考 Web3 的文档。

对于 DApp 来说，最常用的操作是发送一笔交易，一般会调用 web3.js 的 web3.eth.sendTransaction 方法， DApp browser 会监听这个方法调用，显示一个 modal 弹层让用户看到交易的信息，用户可以输入密码签名，然后发送交易，交易成功后会返回一个 txHash，如果失败了会返回 error 值。

错误处理

DApp browser 只处理一部分错误 ( 比如用户输错了密码), 大部分交易的错误会返回给 DApp, DApps 应该处理这些错误并提示给用户. 我们已经对错误的内容做了 i18n 的处理，大多数时候你可以直接弹出 error.message。

gas

我们建议 DApp 在发送交易时，自己设置 gas 和 gasPrice, 因为一般情况下 DApp 会知道精确的值应该是什么，如果 DApp 没有传 gas 参数，我们会调用 web3.eth.estimateGas 去估算一个值。

transaction.signTransaction

signTransaction 只对交易进行签名而不发送，会直接返回签名结果。

⚠️ 不推荐使用: API 在 2.1.5 版本被移除。

transaction.signTransaction

var params = {
  to: "0x0fa38abec02bd4dbb87f189df50b674b9db0b468",
  from: web3.eth.defaultAccount,
  value: "1250000000000000",
};

imToken.callAPI(
  "transaction.signTransaction",
  params,
  function (err, signature) {
    if (err) {
      alert(err.message);
    } else {
      alert(signature);
    }
  }
);

navigator

navigator.getOrientation

获得 APP 当前的 orientation 状态，返回 'LANDSCAPE' 或 'PORTRAIT'

navigator.getOrientation

imToken.callAPI('navigator.getOrientation', function(err, result) {
  console.log(result)
})

navigator.setOrientation

设置 APP 横屏或者竖屏

navigator.setOrientation, 参数为 'landscape' 和 'portrait'

imToken.callAPI('navigator.setOrientation', 'landscape')

navigator.closeDapp

关闭当前 DApp 页面，返回到 DApp列表页

navigator.closeDapp

imToken.callAPI('navigator.closeDapp')

navigator.goBack

返回到历史记录的上一页， 类似 history.go(-1) 如果没有上一页，将会退出当前 DApp

navigator.goBack

imToken.callAPI('navigator.goBack')

navigator.configure

配置导航栏样式，2.5.0 及之后版本可用。

配置项	含义	可选值	默认值
orientation	设备方向	landscape/portrait	portrait
navigationStyle	导航栏样式	default/transparent	default
navigatorColor	导航栏背景色	任何颜色(CSS中的格式)	white

当 navigationStyle 为 transparent 时，导航栏为透明，这时候 navigatorColor 的配置不会生效；

为了给用户带来更好的体验，建议 - 游戏类 DApp 将 navigationStyle 配置为 transparent - 其他 DApp 将导航栏背景色配置与您的 DApp 主色调一致

navigator.configure

imToken.callAPI('navigator.configure', {
  navigatorColor: '#008cd5',
})

navigator.routeTo

导航进入 imToken App 的某个特殊页面，例如进入某个 DApp 页面。

navigator.routeTo

imToken.callAPI('navigator.routeTo', {
  screen: 'DappView',
  passProps: {
    title: 'DApp API Examples',
    url: 'https://consenlabs.github.io/dapp-sdk-doc/index.html',
  },
})

native

native.alert

显示一个 native 的警告框，类似 window.alert

Params	Type	Required	Default	Description
message	string	true	null	alert 的内容

native.alert

imToken.callAPI('native.alert', 'winner winner, chicken dinner！')

native.toast

显示一个 native 的 toast，用来展示信息

Params	Type	Required	Default	Description
message	string	true	null	信息内容
type	string	false	info	信息类型['info', 'warnning', 'success']
align	string	false	top	对齐方式['top', 'center', 'bottom']
model	string	false	banner	显示方式['banner', 'alert']
duration	number	false	1500	显示时长

native.toast

imToken.callAPI('native.toast', {
  type: 'info',
  message: 'hello world',
  align: 'top',
  model: 'banner',
  duration: 1000 * 1,
})

native.confirm

显示一个 native 的确认框, 类似 window.confirm, 如果用户点击了 取消 按钮， 将会返回一个 error 对象。

Params	Type	Required	Default	Description
title	string	true	null	dialog title
message	string	true	null	dialog content
cancelText	string	true	null	cancel button text
confirmText	string	true	null	confirm button text

native.confirm

imToken.callAPI('native.confirm', {
  title: 'quick question',
  message: 'is Javascript the worst language?',
  cancelText: 'no',
  confirmText: 'yes',
}, function(err, result) {
  if(err) {
    console.log('no')
  } else {
    console.log('yes')
  }
})

native.selectPicture

从相册中选择一个图片，或者拍照，返回图片的 base64 数据 (默认是 jpeg)

Params	Type	Required	Default	Description
maxWidth	number	false	null	返回的内容会被裁剪
maxHeight	number	false	null	返回的内容会被裁剪
allowsEditing	boolean	false	false	开启 iOS 系统内置的图片编辑功能
quality	number	false	1	图片质量, 取值 0 到 1

*response: *

property	Type	Description
data	string	base64 data, 默认前缀 'data:image/jpeg;base64,'
width	number	image width
height	number	image height
fileSize	number	file size (b)

native.selectPicture

imToken.callAPI('native.selectPicture',{
  maxWidth: 400,
  maxHeight: 200
}, function (err, ret) {
  if(err) {
    alert(err.message)
  } else {
    document.getElementById('imgContainer').src = ret.data
  }
})

native.setClipboard

设置文本到用户剪贴板

Params	Type	Required	Default	Description
text	string	true	null	文本内容

native.setClipboard

imToken.callAPI('native.setClipboard', 'are you ok?')

native.share

调用一个分享组件

Params	Type	Required	Default	Description
title	string	true	null	title
message	string	true	null	content
url	string	true	null	link, 如果你要分享一个图片， 可以设置 url 为图片的 base64 data
type	string	false	null	分享的内容类型，如果分享图片需要设置，比如 'image/png'

native.share

imToken.callAPI('native.share', {
    title: 'dapp example',
    message: 'this is example of dapp sdk',
    url: location.href,
  }, function (err, ret) {
    if(err) {
      alert(err.message)
    } else {
      alert('share success!')
    }
  })

native.scanQRCode

打开一个二维码扫描, 返回二维码的文本内容

native.scanQRCode

imToken.callAPI('native.scanQRCode', function (err, text) {
    if(err) {
      alert(err.message)
    } else {
      alert(text)
    }
  })

user

user.showAccountSwitch

唤起一个钱包选择器， 用户可以选择一个钱包，返回钱包地址。

如果用户取消选择，将返回错误，错误信息为“用户取消操作”。

user.showAccountSwitch

imToken.callAPI('user.showAccountSwitch', {chainType: null}, function(err, address){
  if(err) {
    alert(err.message)
  } else {
    alert(address)
  }
})

这会在用户的设备上唤起一个钱包选择器，返回用户手动选择的钱包地址

如果你想钱包选择器只显示 bitcoin 地址供选择，可以把上面的 chainType 字段改成 'BITCOIN'。

device

device.getCurrentLanguage

获取用户当前的语言设置，如果 DApp 需要支持多语言，这个信息可能会有用，不过我们已经在 DApp 的 url 上加上了 locale 参数，大多数情况下你不需要调用这个 API

可用的 locale:

• zh-CN
• en-US
• zh-Hant-US
• zh-Hant-HK
• zh-Hant-TW

device.getCurrentLanguage

imToken.callAPI('device.getCurrentLanguage', function(err, language) {
  if(err) {
    alert(err)
  } else {
    alert(language)
  }
})

device.getCurrentCurrency

获取用户当前的货币单位设置

可用的 currency:

• CNY
• USD
• TWD
• HKD

device.getCurrentCurrency

imToken.callAPI('device.getCurrentCurrency', function(err, currency) {
  if(err) {
    alert(err)
  } else {
    alert(currency)
  }
})

others

wallet_addEthereumChain

添加自定义 Ethereum 节点至钱包应用。

此接口与 Ethereum 官方文档提供的 RPC 接口类似，可以访问 ethereum EIP 3085 了解更多信息。

⚠️ 注意: 此接口需要应用版本高于 2.8.4.

Params	Type	Required	Default	Description
chainId	string	true	null	链的整数 ID，十六进制字符串
chainName	string	true	null	链的描述名
nativeCurrency	NativeCurrency	true	null	currency 配置
nativeCurrency.name	string	true	null
nativeCurrency.symbol	string	true	null	2 - 6 字符长度
nativeCurrency.decimals	string	true	null
rpcUrls	string[]	true	null	一个或多个 RPC 端点 url
blockExplorerUrls	string[]	false	null	一个或多个浏览器地址

wallet_addEthereumChain

type EthereumChain = {
  chainId: string;
  chainName: string;
  nativeCurrency: {
    name: string;
    symbol: string; // 2-6 characters long
    decimals: number; // 18
  };
  rpcUrls: string[];
  blockExplorerUrls?: string[];
};
const chain: EthereumChain = {
  chainId: "0x64",
  chainName: "xDAI Chain",
  rpcUrls: ["https://dai.poa.network"],
  iconUrls: [
    "https://xdaichain.com/fake/example/url/xdai.svg",
    "https://xdaichain.com/fake/example/url/xdai.png",
  ],
  nativeCurrency: {
    name: "xDAI",
    symbol: "xDAI",
    decimals: 18,
  },
};

window.ethereum.request({
  method: "wallet_addEthereumChain",
  params: [chain],
});

error code

error code	Description
1001	用户取消了操作

Wallet Connect

前面我们说的 DApp Browser 都是 DApp 运行在 imToken 钱包的浏览器中，如果 DApp 运行在 PC 端、Native APP、或者系统浏览器中，那么就需要用到 Wallet Connect 与 imToken 连接。

imToken 2.5.8 版本开始， 实现了 Wallet Connect 的支持，这样用户可以通过扫码连接 PC 浏览器中的 DApp 和 imToken 钱包，通过 imToken 来使用 PC 浏览器 中的 DApp，对于实现了 Wallet Connect 的移动端 DApp，也可以通过 deeplink 的方式调用 imToken 来完成签名。

关于 Wallet Connect 的开发文档，请参考官方文档 https://docs.walletconnect.org/quick-start/dapps 。

如果你想通过 deeplink 准确地唤起 imToken 钱包，那么需要在 Wallet Connect 协议前面增加 imtokenv2://wc?uri= 前缀，例如:

imtokenv2://wc?uri=wc:00e46b69-d0cc-4b3e-b6a2-cee442f97188@1?bridge=https%3A%2F%2Fbridge.walletconnect.org&key=91303dedf64285cbbaf9120f6e9d160a5c8aa3deb67017a3874cd272323f48ae

debug

在 url 上增加一个 ___debug 参数会默认在页面中添加一个用于调试的 console，比如 https://ens.token.im/?___debug=1 ，在页面的右下角会出现一个 vConsole 的按钮，点击可以打开 console 控制台。

多语言处理

当用户打开 DApp 时，我们会在 http request header 上设置 accept-language 字段, 这个值和用户的 imToken APP 语言保持一致， 比如:

Accept-Language: zh-CN,zh;q=0.9,en-US;q=0.8,en;q=0.7,*;q=0.6

我们建议优先检测 Accept-Language 字段，另外也可以从 URL 上检测， 我们会在 DApp 的 URL 上增加一个 locale 字段， 比如: https://ens.token.im/?locale=en-US

deeplink

通过 deeplink 进入某个 DApp 页面

imtokenv2://navigate?screen=DappView&url=https://token.im

对于 navigate 后面的 queryString 参数，需要 encodeURIComponent 编码。

example

这里有一个 API demo example