Skip to content
This repository has been archived by the owner on May 10, 2021. It is now read-only.

Commit

Permalink
Feature/structural doc changes (#136)
Browse files Browse the repository at this point in the history 
* Structural changes to move to /docs folder

* Adding frontmatter to guides and tutorials

* Splitting out a nav menu section for tutorials

* Update link to docs

* Copy updates for legibility and header placement

* Move tutorial code to examples directory

* Add docs folder to npm ignore, fix links and title change for guides

* Add proper code designations to code blocks.

* Generate docs from template
  • Loading branch information
@localredhead
localredhead committed May 23, 2018
1 parent f77dada commit ad43f7b
Show file tree
Hide file tree
Showing 13 changed files with 1,008 additions and 196 deletions.
4 changes: 0 additions & 4 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,12 +28,8 @@ coverage
lib
dist

#Docs
docs

.DS_Store


integration-test/Connect.js

integration-test/karma.conf.js
Expand Down
1 change: 1 addition & 0 deletions .npmignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,3 +4,4 @@ npm-debug.log*
coverage
examples
test
docs
201 changes: 23 additions & 178 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,9 @@ For any questions or library support reach out to the [uPort team on riot](https

## <a name="getting-started"></a>Getting started with uPort

For additional documentation on all functionality [visit our docs](https://github.com/uport-project/uport-connect/blob/develop/DOCS.md). For a quick start continue below.
For additional documentation on all functionality [visit our docs](https://github.com/uport-project/uport-connect/blob/develop/docs/reference/index.md). For a quick start continue below.

For a more interactive quick start visit [developer.uport.me](https://developer.uport.me)
For a more interactive quick start visit [developer.uport.me](https://developer.uport.me/gettingstarted)

### <a name="quick-start"></a> Quick Start

Expand Down Expand Up @@ -84,181 +84,6 @@ var uport = new uportconnect.Connect('MyDApp')

For a more in depth quick start example follow our [tutorial for building a simple dapp](https://github.com/uport-project/uport-connect/blob/develop/tutorial/tutorial.md) or locally open the `/tutorial` folder. This simple example will show you how to use our default QR flow to connect and create transactions to send ether or interact with smart contracts.

### <a name="frontend"></a> Frontend Library Specific Fixes
Each Frontend Library React, Angular, Vue, etc... can sometimes require specific configuration settings. To prevent developers from solving the same problems twice we're going document Library specific issues on a case-by-case basis.

#### <a name="angular"></a> Angular
When adding the `uport-connect.js` library to an Angular project please install the `crypto-browserify` module as a project dependency and create a path alias pointing `crypto` to the `crypto-browserify` module.

This will fix a `crypto.createHash()` undefined error.

```
"paths": {
"crypto": ["../node_modules/crypto-browserify/index.js"]
}
```


#### <a name="frontend-other"></a> Other Frontend Libraries
Are you experiencing other Frontend Library specific issues?

Let us know in <a href="https://github.com/uport-project/uport-connect/issues"> the issues</a>.

---------------------------------------------

## <a name="usage-guide"></a> Usage Guide

The following Connect object is the primary interface you will use. All details and additional documentation can be found in [our docs](https://github.com/uport-project/uport-connect/blob/develop/DOCS.md).

* [Connect](https://github.com/uport-project/uport-connect/blob/develop/DOCS.md#Connect) ⇐ <code>[ConnectCore](https://github.com/uport-project/uport-connect/blob/develop/DOCS.md#ConnectCore)</code>
* [new Connect(appName, [opts])](https://github.com/uport-project/uport-connect/blob/develop/DOCS.md#new_Connect_new)
* [.getWeb3()](https://github.com/uport-project/uport-connect/blob/develop/DOCS.md#Connect+getWeb3) ⇒ <code>web3</code>
* [.getProvider()](https://github.com/uport-project/uport-connect/blob/develop/DOCS.md#ConnectCore+getProvider) ⇒ <code>[UportSubprovider](https://github.com/uport-project/uport-connect/blob/develop/DOCS.md#UportSubprovider)</code>
* [.requestCredentials([request], [uriHandler])](https://github.com/uport-project/uport-connect/blob/develop/DOCS.md#ConnectCore+requestCredentials) ⇒ <code>Promise.&lt;Object, Error&gt;</code>
* [.requestAddress([uriHandler])](https://github.com/uport-project/uport-connect/blob/develop/DOCS.md#ConnectCore+requestAddress) ⇒ <code>Promise.&lt;String, Error&gt;</code>
* [.attestCredentials(credential, [uriHandler])](https://github.com/uport-project/uport-connect/blob/develop/DOCS.md#ConnectCore+attestCredentials) ⇒ <code>Promise.&lt;Object, Error&gt;</code>
* [.request(request)](https://github.com/uport-project/uport-connect/blob/develop/DOCS.md#ConnectCore+request) ⇒ <code>Promise.&lt;Object, Error&gt;</code>
* [.contract(abi)](https://github.com/uport-project/uport-connect/blob/develop/DOCS.md#ConnectCore+contract) ⇒ <code>Object</code>
* [.sendTransaction(txobj)](https://github.com/uport-project/uport-connect/blob/develop/DOCS.md#ConnectCore+sendTransaction) ⇒ <code>Promise.&lt;Object, Error&gt;</code>

### <a name="communication"></a> Communication

This library manages communication between your application and the mobile app. This communication channel differs depending on the environment in which your app runs and the parameters which you specify. In general, communication consist of a request and a response. This library helps you encode all supported requests. The mobile app understands requests encoded as Uniform Resource Identifier's (URI) with a set of params. These URIs are the strings which must be communicated to the mobile device. All functions which create a request will call a `uriHandler` function which consumes this URI string. This `uriHandler` allows both default and custom means of display and communication.

#### <a name="default-qr"></a> Default QR flow

When the library is loaded on a non-mobile device the library will use QR codes to pass information to the mobile application. To receive a response the library will query a messaging server. You will be able to run your own messaging server or utilize other communication channels, but by default this is provided. We provide a default QR-code display function, which injects a `<div>` containing the QR-code into the DOM. Any function which makes a request to the mobile app will bring up this QR flow.

Using the default QR is the quickest way to start but in many cases you may want to change the QR display, embed the QR codes in different parts of your app, change the display depending on the request, or generate QR codes in once place and show them in another. We provide flexible configs to meet your needs. You can set a default `uriHandler` to be used with every request from the instantiated Connect object or you can can pass a `uriHandler` with each function call which makes a request. The functions which create a request should be clear from the docs.

Instantiate a Connect object with a default `uriHandler`. This URI handler will be called with the request URI on every request.

```js
const uport = new Connect('MyDApp', {
uriHandler: (uri) => {
// ex. show URI handler, create QR code or create a button to send a user to the mobile app
}
})
```

Every function which creates a request can be given a `uriHandler`. When given a URI handler it will ignore the default `uriHandler` with which the object was instantiated.

```javascript
const uriHandler = (uri) => {
// ex. show URI handler, create QR code or create a button to send a user to the mobile app
}
uport.requestCredentials({}, uriHandler).then((credentials) => {
// requestCredentials will call uriHandler with a request encoded as URI string
})
```

URIs are not QR code URIs. If you want to generate a QR code from these request URIs, you can use the following function provided in this library.

```javascript
import { QRUtil } from 'uport-connect'

const uriHandler = (uri) => {
// Creates a QR code URI, this is also a good place to you used any QR code library you prefer.
const qrCode = QRUtil.getQRDataURI(uri)
// A QR cod URI can then be used in a html img tag <img src="${qrCode}"/>
}
```

#### <a name="default-mobile"></a> Default Mobile Requests

By default `uport-connect` will detect if the library is loaded on a mobile device. When on a mobile device it will call the default `mobileUriHandler` function which consumes a URI encoded request. When on a mobile device it assumes that the uPort app is on the same device, it will set the window URL to the request URI which will bring up a prompt to open that URI in the uPort app. To return a response the mobile app will call a URL which encodes the response and return control to the calling app. There is also a great deal of flexibility with the `mobileUriHandler`, the following options may be useful.


Instantiate a Connect object with a default `mobileUriHandler`. This mobile URI handler will be called with the request URI on every request from a mobile device.

```js
const uport = new Connect('MyDApp', {
mobileUriHandler: (uri) => { ... }
})
```

If you want all requests to be handled by your own `uriHandler`. For example you many not want to rely on our default device detection and include your own or set different rules. If you know your application will always be run on a particular device, for example in a native app then this is also useful.

```js
const uport = new Connect('MyDApp', {
isMobile: false
})
// Then set a default uriHandler or pass a uriHandler for each function which makes a request
```

#### <a name="push-notifications"></a> Push Notifications

An alternative means to communicate with a user's uPort app is through push notifications. This requires an initializing request using one of the flow above, then all requests can be made with push notifications. Using push notification requests requires requesting an additional permission from a uPort user. Thus only use push notifications when you believe it improve your app's user experience and/or your application has some limiting factor that necessitates use. (for example requests which are too large to place in a QR code).

```javascript
uport.requestCredentials({
notifications: true
}).then((credentials) => { ... })
// Then all future requests will use push notifications if permission is granted.
```

### <a name="ethereum"></a> Ethereum Interactions and Transactions

`uport-connect` can be used to create a web3 object wrapped with uPort functionality. If you already have an existing application built on ethereum using web3 then this may be the simplest uPort integration. If you want to use alternatives to web3 then `uport-connect` can create a web3 style provider wrapped with uPort functionality and can be used in any library which supports these providers, for example [ethjs](https://github.com/ethjs/ethjs). If you have no need to use web3, or want more granular control over handling request URIs, then `uport-connect` provides a contract object similar to web3 which can be used to create transactions encoded as URI requests.

#### <a name="web3"></a> Using with web3

We provide a convenience method to create a uPort enabled version of the web3 object:

```javascript
let web3 = uport.getWeb3()
```

After the above setup, you can now use the `web3` object as normal.

The following calls will initiate a uPort request, by default this will show a QR code.

* `web3.eth.getCoinbase()` - returns your uport address, if not set already
* `web3.eth.getAccounts()`- returns your uport address in a list, if not set already
* `web3.eth.sendTransaction(txObj)` - returns a transaction hash
* `myContract.myMethod()` - returns a transaction hash

#### <a name="provider"></a> Using a provider

Create a web3 style provider to use with web3 or other libraries which support these providers. Intercepts the same RPC calls as defined above for the web3 object.

```js
const uportProvider = uport.getProvider()
```

#### <a name="contracts"></a> Contract Object (without web3)

Primary reasons to use this object include; 1) You don't want/need to use web3 2) Using a web3 object will use your default URI handler for every request, if you want different URI handling for different contracts or different contract function calls then you should use this. Each contract function call consumes a `uriHandler` function.

Functionality and use similar to web3 contract object. This contract object is promised based.

```js
const statusContractABI = [
{
"constant": false,
"inputs": [
{
"name": "status",
"type": "string"
}
],
"name": "updateStatus",
"outputs": [],
"type": "function"
}
]

const statusContract = uport.contract(statusContractABI)
const status = statusContract.at("0xB42E70a3c6dd57003f4bFe7B06E370d21CDA8087")

const uriHandler = (uri) => {
// ex. show URI handler, create QR code or create a button to send a user to the mobile app
} slack

status.updateStatus('hello', uriHandler).then(txhash => {
...
})
```
---------------------------------------------

## <a name="development-guide"></a> Development Guide
Expand Down Expand Up @@ -324,7 +149,7 @@ $ npm run build:docs:html
$ open docs/index.html
```
```shell
$ npm run build:docs:md // to generate a DOCS.md markdown file
$ npm run build:docs:md // to generate a markdown file in /docs folder
```

#### <a name="scripts"></a> Scripts
Expand All @@ -346,6 +171,26 @@ $ npm install "git://github.com/uport-project/uport-connect.git#develop" --save
$ (cd node_modules/uport-connect && npm install babel-cli && npm run prepublish)
```

### <a name="frontend"></a> Frontend Library Specific Fixes
Each Frontend Library React, Angular, Vue, etc... can sometimes require specific configuration settings. To prevent developers from solving the same problems twice we're going document Library specific issues on a case-by-case basis.

#### <a name="angular"></a> Angular
When adding the `uport-connect.js` library to an Angular project please install the `crypto-browserify` module as a project dependency and create a path alias pointing `crypto` to the `crypto-browserify` module.

This will fix a `crypto.createHash()` undefined error.

```
"paths": {
"crypto": ["../node_modules/crypto-browserify/index.js"]
}
```

#### <a name="frontend-other"></a> Other Frontend Libraries
Are you experiencing other Frontend Library specific issues?

Let us know in <a href="https://github.com/uport-project/uport-connect/issues"> the issues</a>.


## <a name="contribute"></a> Contributing

Code, test and documentation contributions are welcomed and encouraged. Please read the guidelines below and reach out on our [riot](https://chat.uport.me/#/login) or create an [issue](https://github.com/uport-project/uport-connect/issues) if any contribution is more than trivial. We can help you see where/if it fits into our roadmap and if we are likely to accept. We are also looking to add references to projects using `uport-connect` with example implementations and use cases.
Expand Down
20 changes: 13 additions & 7 deletions tutorial/tutorial.md → docs/guides/tutorial.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,9 @@
---
title: "How to integrate Uport-Connect"
index: 0
category: "tutorials"
type: "content"
---

# How to integrate uPort into your dapp

Expand All @@ -13,24 +19,24 @@ We will assume some familiarity with creating Ethereum applications using the `w

Clone the `uport-connect` repository locally, and build it:

```
```sh
git clone https://github.com/uport-project/uport-connect
cd uport-connect
npm install
npm run build-dist
```

We will be working in the directory `uport-connect/tutorial`.
We will be working in the directory `uport-connect/examples/integration-tutorial`.

Make sure you have the uPort application installed on your mobile device. An iOS beta developer version of the app is currently available through TestFlight. To receive instructions on how to acquire the app please enter your details at the following url <https://uport.me/signup>.
Make sure you have the uPort application installed on your mobile device.

We've created a simple HTML file `uport_tutorial.html` that you can find [here](https://github.com/uport-project/uport-connect/blob/develop/tutorial/uport_tutorial.html). It contains a section for connecting your uPort, one section for a transfer of Ether from your uPort address to another address and a section that sets a simple status message in a smart contract.
We've provided a simple HTML file `uport_tutorial.html` that you can find [here](https://github.com/uport-project/uport-connect/blob/develop/tutorial/uport_tutorial.html). It contains a section for connecting your uPort, one section for a transfer of Ether from your uPort address to another address and a section that sets a simple status message in a smart contract.

In order to test the dapp, all you need to do is open the file `uport_tutorial.html` in a browser. There is a file `uport_tutorial.js` that will contain the JavaScript integration code.
In order to test the dapp, all you need to do is open the file `uport_tutorial.html` in a browser. There is a file `index.js` that will contain the JavaScript integration code.

Consider the necessary code to set up the `web3` object with the uPort provider:

```
```js
const Connect = window.uportconnect.Connect
const appName = 'UportTutorial'
const connect = new Connect(appName, {network: 'rinkeby'})
Expand All @@ -45,7 +51,7 @@ Load the HTML file in your browser and hit "Connect uPort". You should see a QR

The functions that trigger QR codes are

```
```js
web3.eth.getCoinbase() //returns your uport address
web3.eth.getAccounts() //returns your uport address in a list
web3.eth.sendTransaction(txObj) //returns a transaction hash
Expand Down
Loading

0 comments on commit ad43f7b

Please sign in to comment.