NAV
Im token logo imToken API Documentation Tokenlon-SDK DApp-SDK
typescript
  • 介绍
  • Provider
  • callAPI
  • API
  • 中文

    介绍

    此文档用户帮助 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 中。

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

    DApp browser 不会往浏览器环境中注入 web3, 只注入一个基本的 provider, DApp 需要这样调用:

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

    import Web3 from 'web3.js'
    
    if(window.ethereum) {
      window.ethereum.enable().then(accounts => {
    
        console.log(accounts) // 拿到用户 钱包地址
    
        window.web3 = new Web3(window.ethereum) // 初始化 web3 对象
    
        web3.eth.sendTransaction({...}, (txId) => { // 发送交易
    
          console.log(txId)
    
        })
      })
    }
    

    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

    对于 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 只对交易进行签名而不发送,会直接返回签名结果。

    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)
      }
    })
    

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

    navigator.getOrientation

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

    设置 APP 横屏或者竖屏

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

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

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

    navigator.closeDapp

    imToken.callAPI('navigator.closeDapp')
    

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

    navigator.goBack

    imToken.callAPI('navigator.goBack')
    

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

    显示一个 native 的确认框, 类似 window.config, 如果用户点击了 取消 按钮, 将会返回一个 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)
        }
      })
    

    device

    device.getCurrentLanguage

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

    可用的 locale:

    device.getCurrentLanguage

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

    device.getCurrentCurrency

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

    可用的 currency:

    device.getCurrentCurrency

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

    error code

    error code Description
    1001 用户取消了操作