@ -255,11 +261,11 @@ Select "Make public" to make your todos accessible to the public for sharing via
This will call `saveTasks` with the `isPublic` parameter set to `true`, which is used to disable encryption when using `putFile`.
The app will now show all of your todos to anyone who visits the URL displayed with your Blockstack username as a suffix.
The app will now show all of your todos to anyone who visits the URL displayed with your Stacks username as a suffix.
## Sign out and see your public tasks
Select "Sign out" to deauthenticate the app with your Blockstack account.
Select "Sign out" to deauthenticate the app with your Stacks account.
This triggers an event, which
[under the hood](https://github.com/blockstack/blockstack-todos/blob/master/src/components/Header.jsx#L47)
@ -274,16 +280,16 @@ option is then passed to `getFile`, which will lookup where that user's tasks ar
## Sign back in
At this point, you will be logged out from the app but not you'll still have an active session with the Blockstack
app itself on [app.blockstack.org](https://app.blockstack.org). Navigate to app.blockstack.org and select "Sign out" there if you want to deauthenticate the Blockstack app as well.
At this point, you will be logged out from the app but not you'll still have an active session with the Stacks
app itself on [app.blockstack.org](https://app.blockstack.org). Navigate to app.blockstack.org and select "Sign out" there if you want to deauthenticate the Stacks app as well.
Once signed out, select "Sign in" to sign back in with your _Secret Key_.
If you've previously deauthenticated the Blockstack app, you'll see a prompt to enter your _Secret Key_:
If you've previously deauthenticated the Stacks app, you'll see a prompt to enter your _Secret Key_:
The above screen will be ommitted if you have an active session with the Blockstack app already.
The above screen will be ommitted if you have an active session with the Stacks app already.
Then you'll be presented with the option to select an existing username associated with your _Secret Key_ or
create a new one if you wish to authenticate the app with a different identity and data set:
@ -294,6 +300,6 @@ You'll now see your todos as an authenticated user for the username you've chose
## Learn more
Read [the Blockstack Connect guide](/authentication/connect) and
[the blockstack.js reference](https://blockstack.github.io/blockstack.js/) to learn more about the
Read [the Stacks Connect guide](/authentication/connect) and
[the stacks.js reference](https://blockstack.github.io/blockstack.js/) to learn more about the
description: Learn what Connect is and how to integrate it into an app.
experience: beginners
duration: 15 minutes
@ -10,34 +10,34 @@ images:
## Introduction
Blockstack Connect is a JavaScript library for integrating Blockstack authentication, data storage, and smart contracts into your app.
Stacks Connect is a JavaScript library for integrating Stacks authentication, data storage, and smart contracts into your app.
The library empowers you to:
- Register new users with a pre-built onboarding flow that quickly educates them as to the privacy benefits of using your app with Blockstack and provisions a "Secret Key" that secures their identity and data against the Stacks blockchain.
- Register new users with a pre-built onboarding flow that quickly educates them as to the privacy benefits of using your app with Stacks authentication and provisions a "Secret Key" that secures their identity and data against the Stacks blockchain.
- Authenticate users when they return to your app using that same Secret Key.
- Prompt users to sign transactions with smart contracts as written in Clarity and published to the Stacks blockchain.
## How does this compare to `blockstack.js`?
## How does this compare to `stacks.js`?
Although [`blockstack.js`](https://github.com/blockstack/blockstack.js) can also be used to authenticate users, it implements the deprecated [Blockstack Browser](https://browser.blockstack.org/) and lacks any pre-built onboarding UI that educates users as to how your app is more secure for having implemented Blockstack. As such, we advise that you use `blockstack.js` for all other functionality apart from authentication, such as saving and retrieving user data with Gaia.
Connect uses stacks.js under the hood to construct and decode authentication requests. It provides pre-built onboarding UI that educates users as to how your app is more secure for having implemented Stacks authentication. You will need to use `stack.js` packages for storage and transactions.
## Start building with Blockstack Connect
## Start building with Stacks Connect
Head over to the [to-do app tutorial](/authentication/building-todo-app) to learn how to build apps with Blockstack Connect. For interaction with Stacks accounts and smart contracts with Blockstack Connect see the [transaction sigining section](/smart-contracts/signing-transactions).
Head over to the [to-do app tutorial](/authentication/building-todo-app) to learn how to build apps with Stacks Connect. For interaction with Stacks accounts and smart contracts with Stacks Connect see the [transaction sigining section](/smart-contracts/signing-transactions).
## Installation
With yarn:
```bash
yarn add @blockstack/connect
yarn add @stacks/connect
```
With npm:
```bash
npm install --save @blockstack/connect
npm install --save @stacks/connect
```
## Usage
@ -68,6 +68,7 @@ export interface AuthOptions {
| finished | function | | false | 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. |
| sendToSignIn | boolean | false | true | Whether the user should go straight to the 'sign in' flow (false) or be presented with the 'sign up' flow (true) instead. |
| userSession | UserSession | | true | pass a `UserSession` instance to use for authentication. If it's not passed, `@blockstack/connect` will create one for you. |
| userSession | UserSession | | false | pass a `UserSession` instance to use for authentication. If it's not passed, `@stacks/connect` will create one for you. |
### In React Apps
@ -76,7 +77,7 @@ If you're using `connect` in a React app, then the best option is to include `co
First, setup the `Connect` provider at the "top-level" of your app - probably next to wherever you would put a Redux provider, for example.
```jsx
import { Connect } from '@blockstack/connect';
import { Connect } from '@stacks/connect';
const authOptions = {
redirectTo: '/',
@ -95,7 +96,7 @@ const App = () => <Connect authOptions={authOptions}>// the rest of your app's c
Later, when you want to begin the onboarding process, use the `useConnect` hook to get `connect`'s `doOpenAuth` method.
```jsx
import { useConnect } from '@blockstack/connect';
import { useConnect } from '@stacks/connect';
const SignInButton = () => {
const { doOpenAuth } = useConnect();
@ -110,15 +111,15 @@ To send the user straight to sign in, call `doOpenAuth(true)`.
### In ES6 (non-React) apps
If you aren't using React, or just want a simpler API, then you can use the `showBlockstackConnect` method.
If you aren't using React, or just want a simpler API, then you can use the `showStacksConnect` method.
```jsx
import { showBlockstackConnect } from '@blockstack/connect';
import { showStacksConnect } from '@stacks/connect';
const authOptions = {
/** See docs above for options */
};
showBlockstackConnect(authOptions);
showStacksConnect(authOptions);
```
#### Sign In
@ -127,27 +128,27 @@ To send the user straight to sign in, include `sendToSignIn: true` in your `auth
#### Note about dependency size:
If you're building a non-React app, note that importing `@blockstack/connect` will add React dependencies to your JavaScript bundle. We recommend using something like [Webpack resolve aliases](https://webpack.js.org/configuration/resolve/) to replace `react` with `preact` in production, which reduces your bundle size. Check out [our own webpack.config.js file](https://github.com/blockstack/ux/blob/master/packages/connect/webpack.config.js#L87:L95) to see how we use this for production builds.
If you're building a non-React app, note that importing `@stacks/connect` will add React dependencies to your JavaScript bundle. We recommend using something like [Webpack resolve aliases](https://webpack.js.org/configuration/resolve/) to replace `react` with `preact` in production, which reduces your bundle size. Check out [our own webpack.config.js file](https://github.com/blockstack/ux/blob/master/packages/connect/webpack.config.js#L87:L95) to see how we use this for production builds.
If you're using the hosted version of `@blockstack/connect` (described below), then you already have a production-optimized bundle.
If you're using the hosted version of `@stacks/connect` (described below), then you already have a production-optimized bundle.
### Using a hosted version of `@blockstack/connect`
### Using a hosted version of `@stacks/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](https://unpkg.com/).
@ -158,7 +159,7 @@ To make sure your app handles this gracefully, you'll need to handle the case wh
`${authOptions.redirectTo}?authResponse=....`
To finalize authentication with this flow, you'll need to utilize the `UserSession` methods `isSignInPending()` and `handlePendingSignIn()`. For more information, check out the [blockstack.js API reference](https://blockstack.github.io/blockstack.js/).
To finalize authentication with this flow, you'll need to utilize the `UserSession` methods `isSignInPending()` and `handlePendingSignIn()`. For more information, check out the [stacks.js API reference](https://blockstack.github.io/blockstack.js/).
```js
const userSession = new UserSession(appConfig);
@ -172,20 +173,20 @@ if (userSession.isSignInPending()) {
## 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.
Stacks authentication is valuable to users, but it can also be a barrier to those unfamiliar with Stacks. 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
### Delay Stacks 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.
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 Stacks authentication. 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.
Many new users to your app will not be familiar with Stacks authentication yet and will be hesitant to click a Stacks-branded button. Provide a generic button for users that are new to your app and Stacks. Stacks Connect will introduce new users to Stacks authentication 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.
You can point users to a specific part of the Stacks App. For instance, a “Sign in” button on your website can redirect users to the sign in flow of the Stacks 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.
Ken
4 years ago