update to version 0.3.0 (#20)

* Add a more robust getting started section * Rename API Ref section * add headless mode to config in README.md * added babel eslint plugin * add headless mode status to all event logs * Add tests with headless mode implemented * Add headless mode check to UI calls * made onboarding a no-op if headless mode is enabled * added changes to readme * fixed type * ensured that custom onboard images work * Made all error objects consistent * updated tests to read message property instead of msg * removed unecessary variable from test * update for npm (package name and doc * patch version update for doc change * changed onboard from no-op to checking the user environment and reporting back to dev what stage the user is at * Add CircleCI config file (#15) * Add CircleCI config file * Update CI config to save node_modules * Add CircleCI deployment to S3 (#16) * Add CircleCI staging deployments for develop branch * Ensure we use the correct value for cache-control on s3 * added missing parenthesis * Update documentation (#18) * Add some sections to the README to explain other features * Capitalisation in README * Change dapp id to API key * update to version 0.3.0 and new script host URL (#19) * Update config.yml * public read access grant public read access to objects synced to s3 bucket * Minor updates to the README
blocknative · Feb 12, 2019 · 3875f01 · 3875f01
1 parent 852b6e4
commit 3875f01
Show file tree

Hide file tree

Showing 18 changed files with 753 additions and 1,380 deletions.
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -0,0 +1,49 @@
+version: 2
+jobs:
+  test:
+    docker:
+      - image: circleci/node:8.15-browsers
+    steps:
+      - checkout
+      - restore_cache:
+          keys:
+          - v1-dependencies-{{ checksum "package.json" }}
+          - v1-dependencies-
+      - run: yarn
+      - run: yarn test
+      - run: yarn build
+      - save_cache:
+          paths:
+            - node_modules
+          key: v1-dependencies-{{ checksum "package.json" }}
+  deploy:
+    docker:
+      - image: circleci/node:8.15-browsers
+    steps:
+      - checkout
+      - run: sudo apt update && sudo apt install awscli
+      - run: yarn
+      - run: yarn build
+      - run: gzip -9 /home/circleci/project/lib/assist.js
+      - run: gzip -9 /home/circleci/project/lib/assist.min.js
+      - run: mv /home/circleci/project/lib/assist.js.gz /home/circleci/project/lib/assist.js
+      - run: mv /home/circleci/project/lib/assist.min.js.gz /home/circleci/project/lib/assist.min.js
+      - run: ls -al
+      - run: echo export VERSION=`awk '/version/{gsub(/("|",)/,"",$2);print $2};' package.json | sed 's/\./-/g'` >> $BASH_ENV
+      - run: mkdir /home/circleci/project/deploy-temp
+      - run: mkdir /home/circleci/project/deploy-temp/${VERSION}
+      - run: mv /home/circleci/project/lib/*.js /home/circleci/project/deploy-temp/${VERSION}/
+      - run: mv /home/circleci/project/lib/* /home/circleci/project/deploy-temp/
+      - run: aws s3 sync /home/circleci/project/deploy-temp s3://staging.assist.blocknative.com --content-type "text/javascript" --content-encoding "gzip" --cache-control "max-age=31536000" --grants read=uri=http://acs.amazonaws.com/groups/global/AllUsers
+workflows:
+  version: 2
+  test_build:
+    jobs:
+      - test
+      - deploy:
+          requires:
+            - test
+          filters:
+            branches:
+              only:
+                - develop
diff --git a/README.md b/README.md
@@ -17,6 +17,29 @@ setup. Supports web3 versions 0.20 and 1.0.
 
 ## Getting Started
 
+To integrate `assist.js` into your dapp, you'll need to do 5 things:
+
+1. Create a free account and get an API key from [blocknative.com](https://blocknative.com)
+2. Install the widget
+3. Initialize the library
+4. Call `onboard`
+5. Decorate your contracts
+
+### Install the widget
+
+#### npm
+
+```
+npm i bnc-assist
+```
+
+#### Script Tag
+The library uses [semantic versioning](https://semver.org/spec/v2.0.0.html).
+The current version is 0.3.0.
+There are minified and non-minified versions.
+Put this script at the top of your `<head>`
+
+
 To integrate `assist.js` into your dapp, you'll need to do 4 things:
 
 1. Install the widget
@@ -33,45 +56,47 @@ There are minified and non-minified versions.
 Put this script at the top of your `<head>`
 
 ```html
-<script src="https://s3.amazonaws.com/bnc-assist/0-2-0/assist.js"
-  integrity="sha384-wtXu8HYQaAoqqmGxbJa799ue405EZi/uNhmblOFpOQOAcL0Tk5wUCYfbELA4OvP6"
-  crossorigin="anonymous"></script>
+<script src="https://assist.blocknative.com/0-3-0/assist.js"></script>
 
 <!-- OR... -->
 
-<script src="https://s3.amazonaws.com/bnc-assist/0-2-0/assist.min.js"
-  integrity="sha384-1pabeMrnax5diGU6TvH3LqKx5EOLvgHy7gv0Kyh7l+qMr/YsQ82W2eXWXcAW6gfz"
-  crossorigin="anonymous"></script>
+<script src="https://assist.blocknative.com/0-3-0/assist.min.js"></script>
 ```
 
-A module will be available on NPM in the coming weeks.
-
-### Initialize the library
+### Initialize the Library
 
 Full documentation of the `config` object is below, but the minimum required `config`
 is as follows:
 
 ```javascript
 var bncAssistConfig = {
-  dappId: dappId,       // [String] The dapp ID supplied to you by Blocknative when you sign up for an account
+  dappId: dappId,       // [String] The API key supplied to you by Blocknative when you sign up for an account
+
   networkId: networkId  // [Integer] The network ID of the Ethereum network your dapp is deployd on.
                         //           See below for instructions on how to setup for local blockchains.
 };
 
 var assistInstance = assist.init(bncAssistConfig);
 ```
 
-### Call `onboard` 
+### Call `onboard`
 
-At some point in your dapp's workflow, you'll want to ensure users have the proper environment.
-This is done by calling `onboard`. Some dapps will call `onboard` immediately upon any page
+At some point in your dapp's workflow, you'll want to ensure users are within an environment which
+will allow them to make transactions, such as a browser with MetaMask, unlocked wallet, etc.
+This is done by calling `onboard`. Some dapps might want to call `onboard` immediately upon any page
 load. Others may wait until loading certain pages or until a certain button is clicked.
 In any event, it is as simple as calling:
 
 ```javascript
 assistInstance.onboard()
   .then(function(success) {
     // User has been successfully onboarded and is ready to transact
+    // This means we can be sure of the follwing user properties:
+    //  - They are using a compatible browser
+    //  - They have a web3-enabled wallet installed
+    //  - The wallet is connected to the config-specified networkId
+    //  - The wallet is unlocked and contains at least `minimumBalance` in wei
+    //  - They have connected their wallet to the dapp, congruent with EIP1102
   })
   .catch(function(error) {
     // The user exited onboarding before completion
@@ -80,22 +105,23 @@ assistInstance.onboard()
   })
 ```
 
-### Decorate your contracts
+### Decorate Your Contracts
 
 The first three steps in the getting started flow will get your users onboarded. This step adds
 transaction support in order to help guide your users through a series of issues that can arise
 when signing transactions.
 
-Using our decorated contracts will also enable some transaction-level metrics tracking to give
-you insights into things like:
+Using our decorated contracts will also enable some anonymised transaction-level metrics to give
+you insights into things including but not limited to:
 
 - How many transactions fail because a user doesn't have enough Ether
 - How many transactions are started but rejected by the user
+- How many users come to your dapp without a web3 wallet
 
 Decorating your contracts is simple:
 
 ```javascript
-var myContract = new web3.eth.Contract(abi, address);
+var myContract = new web3.eth.Contract(abi, address)
 var myDecoratedContract = assistInstance.Contract(myContract)
 
 // and then replace `myContract` with `myDecoratedContract`
@@ -109,24 +135,25 @@ You can then use `myDecoratedContract` instead of `myContract`.
 To speed things up, you can replace the contract after saving the original:
 
 ```javascript
-var myContract = new web3.eth.Contract(abi, address);
-var originalMyContract = myContract;
+var myContract = new web3.eth.Contract(abi, address)
+var originalMyContract = myContract
 myContract = assistInstance.Contract(myContract)
 ```
 
-## API Reference 
+## API Reference
 
 ### Config
 
-A JavaScript Object that is passed to the `init` function.
+A JavaScript Object that is passed to the `init` function. Default values are in [square brackets] where they are set by assist.js.
 
 ```javascript
 var config = {
   networkId: Number, // The network id of the Ethereum network your Dapp is working with (REQUIRED)
-  dappId: String, // The api key supplied to you by Blocknative (REQUIRED)
+  dappId: String, // The API key supplied to you by Blocknative (REQUIRED)
   web3: Object, // The instantiated version of web3 that the Dapp is using
-  mobileBlocked: Boolean, // Defines if the Dapp works on mobile
-  minimumBalance: String, // Defines the minimum balance in Wei that a user needs to have to use the Dapp
+  mobileBlocked: Boolean, // Defines if the Dapp works on mobile [false]
+  minimumBalance: String, // Defines the minimum balance in Wei that a user needs to have to use the Dapp [0]
+  headlessMode: Boolean, // Turn off Assist UI, but still retain analytics collection [false]
   messages: {
     // See custom transaction messages section below for more details
     txPending: Function, // Transaction is pending and awaiting confirmation
@@ -156,7 +183,8 @@ var config = {
 ### Custom Transaction Messages
 
 The functions provided to the `messages` object in the config, will be
-called with the following object so that a custom string can be returned:
+called with the following object so that a custom message string can be returned:
+
 
 ```javascript
 {
@@ -169,6 +197,7 @@ called with the following object so that a custom string can be returned:
     value: String // The value of the transaction (wei)
   },
   contract: {
+    // This object will be undefined if it is not a contract transaction
     methodName: String, // The name of the method that was called
     parameters: Array // The parameters that the method was called with
   }
@@ -200,24 +229,53 @@ The available ids for the `networkId` property of the config object:
 
 *The kovan testnet is not supported.*
 
-#### Local networks
+#### Local Networks
 
-When you are running locally (e.g. using ganache), set `networkId` to `0`.
-This represents a local network.
+When you are running locally (e.g. using ganache), set `networkId` in the config to the network id that the local network is set to. Any number that is not `1`, `3`, `4` and `42` is valid and will be recognized as a local network. If using the Ganache CLI you can set the network id via the `--networkId` option.
 
 ### Errors
 
-All errors are called with `eventCode` and `msg` properties
+All errors are called with `eventCode` and `message` properties.
 
 #### Example
 
 ```javascript
 {
   eventCode: 'initFail',
-  msg: 'A api key is required to run assist'
+  message: 'An API key is required to run assist'
 }
 ```
 
+#### Error Codes
+
+The following are the possible error codes from assist.js.
+
+```
+initFail          - initialization of the library failed
+mobileBlocked     - mobile browsers are blocked from accessing this dapp
+browserFail       - browser is not compatible with web3.js wallets
+walletFail        - user does not have a web3-enabled wallet installed
+walletEnableFail  - user has not logged into their wallet
+networkFail       - user's web3 wallet is not connected to the correct network
+nsfFail           - user does not have enough funds in their wallet
+```
+
+### Headless Mode
+
+By default, assist will create UI elements in your application at certain times to guide users. You can disable this feature and run assist in "headless mode" by setting `headlessMode: true` in the config. This still enables you to collect analytics, but won't change the underlying behaviour of your application at all.
+
+### Mobile Dapps
+
+By default assist's UI elements are responsive and support mobile displays, however some dapps don't work effectively in mobile viewports or with mobile web3 providers like Status.im or Coinbase Wallet. setting `mobileBlocked: true` in the config will detect mobile user agents and direct them to use a desktop browser instead.
+
+### Minimum Balance
+
+By supplying an amount of wei to the `minimumBalance` option of the config, developers can limit access to their dapp to users who have at least this much ETH in their wallet.
+
+### Repeat Transactions
+
+Assist will detect transactions which look to be repeated. We notify users of repeat transactions when we see sequential transactions with the same `to` address and the same `value`.
+
 ## API
 
 ### `init(config)`
@@ -243,7 +301,7 @@ var assistLib = assist.init(assistConfig)
 `Promise`
 
 - resolves with onboard success message if user has been successfully onboarded
-- rejects with an error msg if the user exits onboarding before completion. The error will detail the stage of onboarding the user was up to when they exited
+- rejects with an error message if the user exits onboarding before completion. The error will detail the stage of onboarding the user was up to when they exited
 
 #### Example
 
@@ -254,7 +312,7 @@ da.onboard()
   })
   .catch(function(error) {
     // The user exited onboarding before completion
-    console.log(error.msg) // Will let you know what stage of onboarding the user was up to when they exited
+    console.log(error.message) // Will let you know what stage of onboarding the user was up to when they exited
   })
 ```
 
@@ -289,7 +347,7 @@ mydecoratedContract.myMethod().call()
 `Promise` or `PromiEvent` (`web3.js 1.0`)
 
 - resolves with transaction hash
-- rejects with an error msg
+- rejects with an error message
 
 #### Example
 
@@ -299,7 +357,7 @@ da.Transaction(txObject)
     // Transaction has been sent to the network
   })
   .catch(error => {
-    console.log(error.msg) // => 'User has insufficient funds'
+    console.log(error.message) // => 'User has insufficient funds'
   })
 ```
 
@@ -313,17 +371,18 @@ da.Transaction(txObject)
 
 ```javascript
 state = {
+  version: String,
+  validApiKey: Boolean,
+  supportedNetwork: Boolean,
   config: Object,
+  userAgent: String,
+  mobileDevice: Boolean,
+  validBrowser: Boolean,
   legacyWeb3: Boolean,
   modernWeb3: Boolean,
   web3Version: String,
-  web3: Object,
-  userAgent: String,
-  validKey: Boolean,
-  newUser: Boolean,
-  userWelcomed: Boolean,
+  web3Instance: Object,
   currentProvider: String,
-  validBrowser: Boolean,
   web3Wallet: Boolean,
   legacyWallet: Boolean,
   modernWallet: Boolean,
@@ -332,18 +391,21 @@ state = {
   walletEnabled: Boolean,
   walletEnableCalled: Boolean,
   walletEnableCanceled: Boolean,
+  accountBalance: String,
   correctNetwork: Boolean,
-  userCurrentNetworkId: Number,
   minimumBalance: String,
+  correctNetwork: Boolean,
+  userCurrentNetworkId: Number,
   socket: Object,
+  pendingSocketConnection: Boolean,
   socketConnection: Boolean,
   accountAddress: String,
-  accountBalance: String,
   transactionQueue: Array,
   transactionAwaitingApproval: Boolean,
   iframe: Object,
   iframeDocument: Object,
-  iframeWindow: Object
+  iframeWindow: Object,
+  connectionId: String
 }
 ```
 
@@ -360,7 +422,7 @@ da.getState()
 
 ## Contribute
 
-### Installing dependencies
+### Installing Dependencies
 
 #### NPM