@blockstack/connect

A library for building excellent user experiences with Blockstack.

• Demo
• Why?
• Installation
• API
  • AuthOptions
  • In React Apps
  • In ES6 apps
  • Using a hosted version of @blockstack/connect
  • Sending users to sign in immediately
• Design Guidance
  • Delay Blockstack onboarding as long as possible
  • Provide an easy way in for new users
  • Provide a quick way for existing users to sign in
• Local Development

Demo

To get a test feel for the user experience of using connect, you can use Banter.

Why?

Although blockstack.js exposes everything you need to handle authentication with Blockstack, there is still the hard problem of getting users used to the paradigm of authentication that is privacy-first and self-sovereign. Many apps implement their own dialogues before authentication, which explain what Blockstack is and why they use it.

@blockstack/connect provides developers with a plug-and-play API that is simple to use, and provides great, out-of-the-box education that end-users can understand.

Installation

With yarn:

yarn add @blockstack/connect

With npm:

npm install --save @blockstack/connect

API

AuthOptions

Every major method you'll use with connect requires you to pass some options, like the name and icon of your app, and what to do when authentication is finished. In practice, this means you need to define these options, and pass them to the various API methods.

The exact interface you'll use is defined as:

export interface AuthOptions {
  // The URL you want the user to be redirected to after authentication.
  redirectTo: string;
  manifestPath?: string;
  finished?: (payload: FinishedData) => void;
  authOrigin?: string;
  sendToSignIn?: boolean;
  userSession?: UserSession;
  appDetails: {
    name: string;
    icon: string;
  };
}

• redirectTo: The path in your app where users go after sign in.
• appDetails: an optional object which includes appName: string and appIcon: string. This will speed up the process of loading your app's information during onboarding.
• manifestPath: (optional) - the path in your app where your manifest.json file can be found
• finished: (optional) - A callback that can be invoked after authentication. This prevents having to do a whole page refresh in a new tab. One argument is passed to this callback, which is an object with userSession included. If included, then the redirectTo path is ignored, and the user will be logged in automatically.
• authOrigin: (optional) - The URL you'd like to use for authentication. Only necessary for local development of the authenticator.
• sendToSignIn: (optional) - defaults to false. Whether the user should go straight to the 'sign in' flow.
• userSession: (optional) - pass a UserSession instance to use for authentication. If it's not passed, @blockstack/connect will create one for you.

In React Apps

If you're using connect in a React app, then the best option is to include connect's React infrastructure and hooks in your React app.

First, setup the Connect provider at the "top-level" of your app - probably next to wherever you would put a Redux provider, for example.

import { Connect } from '@blockstack/connect';

const authOptions = {
  redirectTo: '/',
  finished: ({ userSession }) => {
    console.log(userSession.loadUserData());
  },
  appDetails: {
    name: 'My Cool App',
    icon: 'https://example.com/icon.png',
  },
};

const App = () => (
  <Connect authOptions={authOptions}>
    // the rest of your app's components
  </Connect>
)

Later, when you want to begin the onboarding process, use the useConnect hook to get connect's doOpenAuth method.

import { useConnect } from '@blockstack/connect';

const SignInButton = () => {
  const { doOpenAuth } = useConnect();

  return (
    <Button onClick={doOpenAuth}>
      Sign In
    </Button>
  )
}

In ES6 apps

If you aren't using React, or just want a simpler API, then you can use the showBlockstackConnect method.

import { showBlockstackConnect } from '@blockstack/connect';

const authOptions = { /** See docs above for options */ };
showBlockstackConnect(authOptions);

Using a hosted version of @blockstack/connect

If you aren't using ES6 imports, you can still use connect! We package the library so that it can be automatically used with unpkg.

First, include the script in your HTML:

<script src="https://unpkg.com/@blockstack/connect/dist/bundle.js" />

Then, you can use API methods under the blockstackConnect global variable:

const authOptions = { /** See docs above for options */ };
blockstackConnect.showBlockstackConnect(authOptions);

Sending users to sign in immediately

Our design guidance, explained below, encourages your app to have a dedicated "Sign In" call-to-action. This will send them immediately to authenticate, with a screen for entering their Secret Key, if they aren't logged in to the authenticator.

To do so, use the authenticate method, and make sure to specify sendToSignIn: true.

import { authenticate } from '@blockstack/connect';

const authOptions = {
  sendToSignIn: true,
  // your other AuthOptions
};
authenticate(authOptions)

Or, if you're using our React hooks, pass true as the first argument in doOpenAuth.

const { doOpenAuth } = useConnect();

doOpenAuth(true);

Design Guidance

Blockstack is valuable to users, but it can also be a barrier to those unfamiliar with Blockstack. The following guidelines serve to remedy that and help you onboard as many new users as you can.

Delay Blockstack onboarding as long as possible

People will often leave apps when things are asked of them before they experience the app. Give them a chance to try your app before you ask them to sign up with Blockstack. For example, a note taking app could let a new user write a couple of notes before prompting them to save their progress.

Provide an easy way in for new users

Many new users to your app will not be familiar with Blockstack yet and will be hesitant to click a Blockstack-branded button. Provide a generic button for users that are new to your app and Blockstack. Blockstack Connect will introduce new users to Blockstack and recognize existing users.

Provide a quick way for existing users to sign in

You can point users to a specific part of the Blockstack App. For instance, a “Sign in” button on your website can redirect users to the sign in flow of the Blockstack App. If you do this, make sure you also have an option that is explicitly for new users and that points to the sign up flow.

To implement this functionality, check out our section on sending users to sign in immediately.

Local Development

There is a test app located in /test-app. cd test-app && yarn && yarn start to run a local react app with fast-refresh.