| 1 | <img src="https://user-images.githubusercontent.com/211411/34776833-6f1ef4da-f618-11e7-8b13-f0697901d6a8.png" height="100" />
|
| 2 |
|
| 3 | [Github](https://github.com/LedgerHQ/ledgerjs/),
|
| 4 | [Ledger Devs Slack](https://ledger-dev.slack.com/)
|
| 5 |
|
| 6 | ## @ledgerhq/hw-transport-webusb
|
| 7 |
|
| 8 | Allows to communicate with Ledger Hardware Wallets.
|
| 9 |
|
| 10 | **\[Web]** **(WebUSB)** – WebUSB [check browser support](https://caniuse.com/webusb).
|
| 11 |
|
| 12 | ### FAQ: "DOM Exception" is triggered when creating the transport
|
| 13 |
|
| 14 | The transport functions `create()` and `listen()` must be called in the context of an user interaction (like a **"click"** event), otherwise it fails with DOM Exception. This is by WebUSB design. You also must run on HTTPS.
|
| 15 |
|
| 16 | ### How to use this transport regarding WebUSB paradigm?
|
| 17 |
|
| 18 | In WebUSB, we have a "permission native" modal that appears when we need to "request" a device. This is required at-least-once for the user to accept, and then we can open the transport without triggering this modal. However, in both cases, it must happen in context of a click like explain above. Our current implementation tradeoff is to abstract this out and only trigger the permission modal if no device are listed. This might change in the future.
|
| 19 |
|
| 20 | In term of UX, there are two classical usecases:
|
| 21 |
|
| 22 | 1. you only need the device at key times, like once to get the address. once to sign a transaction,...
|
| 23 | 2. your app lifecycle requires that you need to access the device at the beginning and/or at any time (like you want to ping with getAddress to get the wallet address)
|
| 24 |
|
| 25 | in (1) case, you can just do your logic in each button (Get Address / Sign Transaction) time (create it, do the logic, close it).
|
| 26 | in (2) case, you will need to have a Connect button that appear when you don’t have the connection yet. and you need to hook to the “disconnect” event to potentially make the UI reflect that and require user to click again on that Connect button, because you can’t automatically `create()`/`open()` again.
|
| 27 |
|
| 28 | ### Support status
|
| 29 |
|
| 30 | WebUSB is currently only supported on Google Chrome / Chromium.
|
| 31 |
|
| 32 | * In Linux, user need to install the [specific udev rules](https://raw.githubusercontent.com/LedgerHQ/udev-rules/master/add_udev_rules.sh)
|
| 33 | * In Mac, it should work.
|
| 34 | * In Windows, [WebUSB does not work out of the box](https://github.com/WICG/webusb/issues/143) but you can fix it with [Zadig](https://zadig.akeo.ie/).
|
| 35 | * In Android Chrome it works.
|
| 36 |
|
| 37 | ## API
|
| 38 |
|
| 39 |
|
| 40 |
|
| 41 | #### Table of Contents
|
| 42 |
|
| 43 | * [TransportWebUSB](#transportwebusb)
|
| 44 | * [Parameters](#parameters)
|
| 45 | * [Examples](#examples)
|
| 46 | * [close](#close)
|
| 47 | * [exchange](#exchange)
|
| 48 | * [Parameters](#parameters-1)
|
| 49 | * [isSupported](#issupported)
|
| 50 | * [list](#list)
|
| 51 | * [listen](#listen)
|
| 52 | * [Parameters](#parameters-2)
|
| 53 | * [request](#request)
|
| 54 | * [openConnected](#openconnected)
|
| 55 | * [open](#open)
|
| 56 | * [Parameters](#parameters-3)
|
| 57 |
|
| 58 | ### TransportWebUSB
|
| 59 |
|
| 60 | **Extends Transport**
|
| 61 |
|
| 62 | WebUSB Transport implementation
|
| 63 |
|
| 64 | #### Parameters
|
| 65 |
|
| 66 | * `device` **USBDevice**
|
| 67 | * `interfaceNumber` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)**
|
| 68 |
|
| 69 | #### Examples
|
| 70 |
|
| 71 | ```javascript
|
| 72 | import TransportWebUSB from "@ledgerhq/hw-transport-webusb";
|
| 73 | ...
|
| 74 | TransportWebUSB.create().then(transport => ...)
|
| 75 | ```
|
| 76 |
|
| 77 | #### close
|
| 78 |
|
| 79 | Release the transport device
|
| 80 |
|
| 81 | Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<void>**
|
| 82 |
|
| 83 | #### exchange
|
| 84 |
|
| 85 | Exchange with the device using APDU protocol.
|
| 86 |
|
| 87 | ##### Parameters
|
| 88 |
|
| 89 | * `apdu` **[Buffer](https://nodejs.org/api/buffer.html)**
|
| 90 |
|
| 91 | Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[Buffer](https://nodejs.org/api/buffer.html)>** a promise of apdu response
|
| 92 |
|
| 93 | #### isSupported
|
| 94 |
|
| 95 | Check if WebUSB transport is supported.
|
| 96 |
|
| 97 | #### list
|
| 98 |
|
| 99 | List the WebUSB devices that was previously authorized by the user.
|
| 100 |
|
| 101 | #### listen
|
| 102 |
|
| 103 | Actively listen to WebUSB devices and emit ONE device
|
| 104 | that was either accepted before, if not it will trigger the native permission UI.
|
| 105 |
|
| 106 | Important: it must be called in the context of a UI click!
|
| 107 |
|
| 108 | ##### Parameters
|
| 109 |
|
| 110 | * `observer` **Observer\<DescriptorEvent\<USBDevice>>**
|
| 111 |
|
| 112 | Returns **Subscription**
|
| 113 |
|
| 114 | #### request
|
| 115 |
|
| 116 | Similar to create() except it will always display the device permission (even if some devices are already accepted).
|
| 117 |
|
| 118 | #### openConnected
|
| 119 |
|
| 120 | Similar to create() except it will never display the device permission (it returns a Promise\<?Transport>, null if it fails to find a device).
|
| 121 |
|
| 122 | #### open
|
| 123 |
|
| 124 | Create a Ledger transport with a USBDevice
|
| 125 |
|
| 126 | ##### Parameters
|
| 127 |
|
| 128 | * `device` **USBDevice**
|