@ -208,7 +208,7 @@ When deleting a todo, the same `putFile` method is used to save a new JSON array
### Publish your todos publicly
If you wish to make your todos accessible to the public for sharing via URL, select "Make public".
Select "Make public" to make your todos accessible to the public for sharing via URL.
@ -218,6 +218,7 @@ The app will now show all of your todos to anyone who visits the URL displayed w
### Sign out and see your public tasks
Select "Sign out" to deauthenticate the app with your Blockstack account.
This triggers an event, which [under the hood](https://github.com/blockstack/blockstack-todos/blob/master/src/components/Header.jsx#L47) calls the [`signUserOut` method](https://blockstack.github.io/blockstack.js/classes/usersession.html#signuserout) of the `UserSession` object.
@ -229,17 +230,20 @@ When you visit this page, the `TodoList.jsx` component detects that there is a u
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.
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*:
Signout is handled in `src/components/App.js`.
The above screen will be ommitted if you have an active session with the Blockstack app already.
```js
handleSignOut(e) {
e.preventDefault();
userSession.signUserOut(window.location.origin);
}
```
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:
Read [the Blockstack Connect guide](/develop/connect/get-started.html) and [the blockstack.js reference](https://blockstack.github.io/blockstack.js/) to learn more about the libraries used in this tutorial.
You'll now see your todos as an authenticated user for the username you've chosen.
## Learn more
Read [the Blockstack Connect guide](/develop/connect/get-started.html) and [the blockstack.js reference](https://blockstack.github.io/blockstack.js/) to learn more about the libraries used in this tutorial.
description: "JavaScript library for integration authentication and smart contracts"
redirect_from:
- /develop/connect/get-started.html
---
# Introduction
# Guide to Blockstack Connect
{:.no_toc}
* TOC
{:toc}
## Introduction
Blockstack Connect is a JavaScript library for integrating Blockstack authentication and smart contracts into your app.
The library empowers you to:
@ -16,7 +22,6 @@ The library empowers you to:
- 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.
## See it in action
## How does this compare to `blockstack.js`?
@ -97,38 +102,102 @@ const App = () => (
)
```
**insert video**
Later, when you want to begin the onboarding process, use the `useConnect` hook to get `connect`'s `doOpenAuth` method.
```javascript
import { useConnect } from '@blockstack/connect';
const SignInButton = () => {
const { doOpenAuth } = useConnect();
return (
<ButtononClick={doOpenAuth}>
Sign In
</Button>
)
}
```
#### Sign In
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.
```javascript
import { showBlockstackConnect } from '@blockstack/connect';
const authOptions = { /** See docs above for options */ };
showBlockstackConnect(authOptions);
```
#### Sign In
As you can see, you simply need to add a "Get started" option to your app homepage and the library will display an introductory modal in the context of your app that explains the privacy benefits of using Blockstack and prepares users to receive a Secret Key instead of entering a traditional email and password.
To send the user straight to sign in, include `sendToSignIn: true` in your `authOptions`.
The modal then triggers a popup in which Blockstack PBC's authenticator generates a 12-word mnemonic Secret Key and instructs the user to save it securely. The authenticator subsequently requests a username from the user, which will be used to identify them in your app and manage their various accounts, before routing them back to your app to start using it.
#### Note about dependency size:
This entire onboarding flow has been designed and tested to optimize the speed in which your new users start using your app with the prerequisite knowledge and credentials.
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/fix/connect-modal-accessibility/packages/connect/webpack.config.js#L87:L95) to see how we use this for production builds.
Here's what users see when returning to an app to sign back in:
If you're using the hosted version of `@blockstack/connect` (described below), then you already have a production-optimized bundle.
**insert video**
### Using a hosted version of `@blockstack/connect`
As you can see, you simply need to add a "Sign in" option to your homepage. The library will trigger a popup in which the authenticator prompts users to simply enter their Secret Key at which point they can resume using your app.
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/).
At whichever point after a user has authenticated to your app, you can trigger the authenticator in a popup once more for them to a sign a transaction against any smart contract you or others have published to the Stacks blockchain.
First, include the script in your HTML:
Connect is built to use popups with the [`window.postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) API, which provides a much better and seamless user experience. However, there are times when this flow can fail. For example, the popup may be blocked, or the `window.postMessage` API might not work properly (which often happens on mobile browsers).
To make sure your app handles this gracefully, you'll need to handle the case where authentication is performed through regular HTTP redirects. With redirects, your users will be sent back to your app at a URL like:
Note how this UI indicates "Testing mode" since transaction signing functionality is currently in beta and designed primarily with developers in mind. However, any Blockstack user who authenticates to your app can use it.
`${authOptions.redirectTo}?authResponse=....`
## Try it out
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/).
Our test app [Banter](https://banter.pub) is built with Blockstack Connect. Select "Get Started" to experience the standardized onboarding flow available to all apps that integrate this library.
```js
const userSession = new UserSession(appConfig);
Separately, you can use the [Blockstack Testnet Demo](https://authenticator-demo.netlify.app/) not only to experience registration and sign in but transaction signing as well.
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.
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.
### Provide a quick way for existing users to sign in
## Start building with Blockstack Connect
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.
Head over to the [Guide to Connect](get-started.html) for installation steps and usage guidelines.
To implement this functionality, check out our section on sending users to sign in immediately.
Hank Stoever
4 years ago
Mark Hendrickson
