Introducing Push Notifications for uPort

Many developers told us that they wanted a better way to interact with their end users, so we added push notifications to the uPort platform. App developers can now send requests and signed credentials directly to a user’s uPort mobile app.

To receive your first push notification, log in to demo.uport.me (a demo site) with your uPort mobile app and request a credential.

Sending Requests to the phone

Developers now have 3 ways of sending requests to the uPort mobile app:

• Mobile App or Mobile Browser: App-link from your mobile native/browser app to the uPort mobile app. Users must be on their phone.
• Desktop Browser: Display a QR Code from your app running in a desktop browser. Users must be sitting in front of the computer.
• Anytime, Anywhere: Send a push notification from a server-side application. Users can be sitting in front of the computer or they can be anywhere. Push notifications are best for maintaining “longer term” relationships with users.

Use Cases/Applications

There are 3 primary types of messages that applications can send to a user:

• Ethereum Transactions for Signing
• Signed Credentials (Verified Claims)
• Credential Sharing Requests

Unlike other methods of sending requests, push notifications are great for handling long-term interactions with your user. For example, you could send them a transaction request to buy or sell a share in a prediction market once an external event has happened, such as a price change or an election result.

A Signed Credential is a verifiable/signed token that users can share with other businesses. Sample use case: if you are a financial exchange, you might send weekly credentials attesting to the average account balance for a user, and they could then share this signed credential in a credit application with a lending platform.

How do I use Push Notifications?

To get started with push notifications, you’ll need to create an app identity for your application using link uPort AppManager. This allows you to create signed requests that are verified as coming from your application.

Using Uport-Connect for POCs and functional prototypes

For development purposes, you can use our uport-connect library to prototype a simple flow in the browser. It’s important to realize that this requires your private keys to be available in the browser, and therefore this should flow should not be used for production apps.

Configure uPort like this:

import { Connect, SimpleSigner } from 'uport-connect'
const uport = new Connect('YOUR APP NAME', {
  clientId: 'YOUR APPLICATION ID FROM APP MANAGER',
  signer: SimpleSigner('YOUR SIGNING KEY FROM APP MANAGER')
})

Send users a request to send them push notifications:

As part of the standard uport-connect log-in flow, you use uport.requestCredentials to ask for specific details from your users. Request push notifications by simply adding notifications: true to the function call:

uport.requestCredentials({
        requested: ['name', 'phone', 'country'],
        notifications: true
      })
      .then((credentials) => {
        console.log(credentials)
        // Store credentials in your app        
      })

The push token is stored inside the uPort object. Any request you send, such as this attestCredentials call, gets sent directly to the user's mobile phone app.

uport.attestCredentials({
      sub: this.props.uport.address,
      claim: {name: this.props.uport.name},
      exp: new Date().getTime() + 2592000000
    })

It is also possible to send Ethereum transaction requests directly to the phone:

const abi = // import from json or have directly in code
const contract = uport.contract(abi).at(contractAddress)
// creates a request for the user to call the sell() function on the smart contract
contract.sell(1000).then(txhash => {
  // verify txhash
})

Using the Uport package in server-side apps

For server-side apps, you should use the uport library directly. (This is also used behind the scenes in uport-connect.) The uPort library creates and builds JWT objects that are used to communicate securely between your app and your user’s uPort mobile app.

First you must configure your uPort object.

import { Credentials, SimpleSigner } from 'uport'
const credentials = new Credentials({
  appName: 'App Name',
  address: 'Application ID'
  signer: SimpleSigner(process.env.PRIVATE_KEY)
})

The SimpleSigner creates a very simple implementation of a signing function. It would be fairly easy to create a similar function delegating signing to an HSM or other more secure implementation.

Then you must request a push notification token from the user to communicate with their device directly. You will need to create a callback end point on your server to receive the response from the app.

const randomToken = ... // generate random number to track request
credentials.createRequest({
  requested:[...],
  callbackUrl: 'https://ourserver.test/receive/' + randomToken,
  notifications: true
}).then(requestToken => {
  // send to browser
})

Once you receive the responseToken on your callback endpoint, you must verify the response using the receive() function, which returns a profile object containing your pushToken, which allows you to communicate with the user.

credentials.receive(responseToken).then(profile => {
  // Store user profile
  // Store push token securely
  console.log(profile.pushToken)
})

You can now use the standard uport Contract tools to send the user transaction requests to sign.

import { Contract } from 'uport'
const abi = // import from json or have directly in code
const contract = Contract(abi).at(contractAddress)
// creates a request for the user to call the sell() function on the smart contract
const txRequest = contract.sell(1000)
credentials.push(user.pushToken, txRequest)

Creating Verified Credentials like this attestation of a user’s average balance is also simply created and sent directly as a push notification:

credentials.attest({ 
    sub:user.address, 
    claim: {averageAccountbalance: 10000}, 
    exp: new Date().getTime() + 2592000000
}).then(attestationJWT =>
    credentials.push(pushToken,`me.uport:add?attestation=${attestationJWT}`))

Conclusion

We see push notifications as a critical functionality for building Ethereum applications that are simple to use and provide real value to the end-user. Now, developers can provide a better and more useful experience for users even when they aren’t at their desktop or in the mobile app. From sending Ethereum transaction requests to creating and sharing verified credentials, push notifications are a user-friendly way to build long-term relationships with your users.