|
1 | | -Wallet Selector One Click Connect is a package that allows apps to bypass the NEAR wallet selector modal and instantly sign users with the click of a button. |
| 1 | +# One Click Connect Wallet Selector |
2 | 2 |
|
3 | | -# Table of Contents |
| 3 | +## Overview |
4 | 4 |
|
5 | | -- [Table of Contents](#table-of-contents) |
6 | | -- [One Click Connect Experiences](#keypom-oneclick-connect-experiences) |
7 | | -- [Installation](#installation) |
8 | | -- [Getting Started](#getting-started) |
9 | | - - [setupOneClickConnect Parameters](#setuponeclickconnect-parameters) |
10 | | - - [How do I trigger OneClick Connect?](#how-do-i-trigger-oneclick-connect) |
11 | | - - [Connection Parameters](#connection-parameters) |
12 | | - - [Optional Secret Key](#optional-secret-key) |
13 | | - - [Example Flow with Secret Key](#example-flow-with-secret-key) |
14 | | - - [Example Flow without Secret Key](#example-flow-without-secret-key) |
15 | | - - [Example Usage](#example-usage) |
| 5 | +The One Click Connect Wallet Selector is a package that integrates with the NEAR wallet selector ecosystem, allowing applications to bypass the traditional NEAR wallet selector modal and enabling users to sign in with a single click. This package significantly reduces friction in the user authentication flow, making the dApp experience more seamless and efficient. |
16 | 6 |
|
17 | | ---- |
| 7 | +## Installation |
18 | 8 |
|
19 | | -# One Click Connect Experiences |
20 | | - |
21 | | -OneClick Connect is a great way to reduce friction for users signing into applications. Currently, the sign in flow for a new user is as follows: |
22 | | - |
23 | | -1. User creates an account. |
24 | | -2. They navigate to an application. |
25 | | -3. Sign-in is clicked. |
26 | | -4. The wallet selector modal is opened and the user needs to scroll to find their wallet. |
27 | | -5. The user clicks their wallet and is redirected to the wallet's website to approve a transaction. |
28 | | -6. The user is redirected back to the app and is signed in. |
29 | | - |
30 | | -As NEAR pushes to abstract crypto complexities away from the end user, this approach is not scalable. Not only are there a lot of clicks and redirects, leading to a loss in user retention, but people must also know which wallet they own. This is a big problem for apps like Sweatcoin, where the wallet logic is hidden from the user. |
31 | | - |
32 | | -The flow that OneClick Connect offers is as follows: |
33 | | - |
34 | | -1. User creates an account. |
35 | | -2. User clicks a button from inside a wallet application. |
36 | | -3. User is instantly signed in and can start using the dApp. |
37 | | - |
38 | | -This flow is much more seamless and removes all the redirects and wallet selector modal friction. |
39 | | - |
40 | | -# Installation |
41 | | - |
42 | | -To install the plugin, run the following command: |
43 | | - |
44 | | -```bash |
| 9 | +```shell script |
45 | 10 | npm install @one-click-connect/wallet-selector |
46 | 11 | # or |
47 | 12 | yarn add @one-click-connect/wallet-selector |
48 | 13 | # or |
49 | 14 | pnpm add @one-click-connect/wallet-selector |
50 | 15 | ``` |
51 | 16 |
|
52 | | -# Getting Started |
| 17 | +## Features |
| 18 | + |
| 19 | +- **Streamlined Authentication Flow**: Eliminates multiple redirects and clicks normally required in the NEAR wallet authentication process. |
| 20 | +- **NEAR Wallet Selector Integration**: Fully compatible with the official NEAR wallet selector, easily integrating alongside other wallet modules. |
| 21 | +- **Customizable Configuration**: Configure network settings, contract IDs, and allowed methods to suit your application's needs. |
| 22 | +- **Enhanced User Experience**: Ideal for applications that want to abstract away crypto complexities from end users. |
| 23 | +- **Direct Sign-in**: Enables users to connect directly from a wallet application to your dApp without intermediary steps. |
53 | 24 |
|
54 | | -Apps on NEAR should be compatible with the official [wallet selector](https://github.com/near/wallet-selector) plugin to enable signing and sending transactions. Like Mintbase Wallet, MyNEARWallet, Meteor Wallet etc, One Click Connect is a simple module for the wallet selector. This means that all you need to do is install the plugin and add its setup function to the wallet selector exactly as you would do with any other wallet. |
| 25 | +## Usage |
55 | 26 |
|
56 | | -To get started, navigate to the app's `setupWalletSelector` code where the selector is initialized. Here, you can specify which wallet modules your app should support. Simply import and add OneClick Connect's `setupOneClickConnect` function to the list of modules and you're good to go! |
| 27 | +The One Click Connect wallet selector can be easily integrated into your existing NEAR wallet selector setup: |
57 | 28 |
|
58 | | -```js |
| 29 | +```javascript |
| 30 | +import { setupWalletSelector } from '@near-wallet-selector/core'; |
59 | 31 | import { setupOneClickConnect } from '@one-click-connect/wallet-selector'; |
60 | 32 |
|
61 | 33 | const selector = await setupWalletSelector({ |
62 | | - network: "testnet", |
63 | | - modules: [ |
64 | | - setupMyNearWallet(), |
65 | | - ..., |
66 | | - setupSender(), |
67 | | - // Add the OneClick Connect function here |
68 | | - setupOneClickConnect({ |
69 | | - networkId: "testnet", |
70 | | - contractId: "guestbook.near-examples.testnet", |
71 | | - methods: ["add_message"], // Optional, defaults to any methods ["*"] |
72 | | - allowance: "250000000000000000000000" // Optional, access key allowance in Yocto, defaults to 1 NEAR |
73 | | - }) |
74 | | - ], |
| 34 | + network: "testnet", |
| 35 | + modules: [ |
| 36 | + // Other wallet modules |
| 37 | + ..., |
| 38 | + // Add the OneClick Connect module |
| 39 | + setupOneClickConnect({ |
| 40 | + networkId: "testnet", |
| 41 | + contractId: "your-contract.near", |
| 42 | + methods: ["method_1", "method_2"] // Optional |
| 43 | + }) |
| 44 | + ] |
75 | 45 | }); |
76 | 46 | ``` |
77 | 47 |
|
78 | | -## setupOneClickConnect Parameters |
| 48 | +### Traditional vs. One Click Connect Flow |
79 | 49 |
|
80 | | -- `networkId`: Either `testnet` or `mainnet`. |
81 | | -- `contractId`: Specifies the contract that the limited access key is capable of calling. |
82 | | -- `methods` (*Optional*): This controls what methods any limited access keys added will be able to call. Defaults to all methods. |
83 | | -- `allowance` (*Optional*): Outlines the allowance for any limited access keys added. This defaults to 1 NEAR. |
| 50 | +**Traditional Flow:** |
| 51 | +1. User creates an account |
| 52 | +2. User navigates to the application |
| 53 | +3. User clicks sign-in |
| 54 | +4. The wallet selector modal opens |
| 55 | +5. User selects their wallet |
| 56 | +6. User is redirected to the wallet website to approve |
| 57 | +7. User is redirected back to the app |
84 | 58 |
|
85 | | -## How do I trigger OneClick Connect? |
| 59 | +**One Click Connect Flow:** |
| 60 | +1. User creates an account |
| 61 | +2. User clicks a button directly from the wallet application |
| 62 | +3. User is instantly signed in and ready to use the dApp |
86 | 63 |
|
87 | | -The OneClick Connect experience will trigger on any page that matches the following URL pattern: |
88 | | - |
89 | | -``` |
90 | | -"http://app.example.com/?connection=tbin329...adwe0vjer" |
91 | | -``` |
92 | | - |
93 | | -The string following `?connection=` is a base64 encoded stringified JSON containing connection information. This JSON can be seen below: |
94 | | - |
95 | | -### Connection Parameters |
96 | | -```ts |
97 | | -connection = { |
98 | | - accountId: string, |
99 | | - walletId: string, |
100 | | - walletTransactionUrl: string | undefined, |
101 | | - chainId: string | undefined, |
102 | | - secretKey: string | undefined, |
103 | | -}; |
104 | | -``` |
| 64 | +## API Reference |
105 | 65 |
|
106 | | -- `accountId`: The account being signed into the destination dApp. |
107 | | -- `walletId`: ID of the wallet being used. For example, `sweat-wallet`. |
108 | | -- `walletTransactionUrl`: This is the URL for a wallet signing transactions. |
109 | | -- `chainId`: Destination chain for the sign in, defaults to NEAR. |
110 | | -- `secretKey`: The secret key for signing transactions on the destination dApp. If undefined, OneClick will try to add it along with the first transaction the user signs. |
| 66 | +### setupOneClickConnect(options) |
111 | 67 |
|
112 | | -Any malformed string following `?connection=` that cannot be base64 decoded and JSON stringified will lead to a failed login. |
113 | | - |
114 | | -### Optional Secret Key |
115 | | -In the development of OneClick, it became apparent that exposing a secret key in the URL could pose a security concern in certain scenarios. For example, if the limited access key was meant to cast a vote in a DAO, then it would be imparative that the key is not exposed in order to ensure the integrity of the vote. This led to the creation of two flows, depending on your security needs. |
| 68 | +The main setup function that configures the One Click Connect module for the NEAR wallet selector. |
116 | 69 |
|
117 | | -#### Example Flow with Secret Key |
118 | | -The first approach is the less secure method, directly exposing the secret key in the URL. The compromise in security grants you a smoother user experience. The flow is as follows: |
| 70 | +#### Parameters |
119 | 71 |
|
120 | | -1. dApp A, that the user is signed into with the full access key, creates a new limited access key for the user in the background |
121 | | -2. This new key is placed into the connection object in the URL |
122 | | -3. User clicks on the URL, signing them into dApp B. From here, they can instantly start signing transactions on dApp B, using the previously generated secret key, without ever needing to open their wallet. |
| 72 | +- **options** (object): |
| 73 | + - `networkId` (string): The NEAR network ID ("mainnet", "testnet", etc.) |
| 74 | + - `contractId` (string): The contract ID your application interacts with |
| 75 | + - `methods` (string[]): Optional array of contract methods to allow |
123 | 76 |
|
124 | | -#### Example Flow without Secret Key |
125 | | -The second approach is more secure but includes an extra step. Rather than dApp A creating a limited access key before redirecting, this occurs when the user attempts to sign the first transaction on dApp B: |
| 77 | +#### Returns |
126 | 78 |
|
127 | | -1. dApp A, that the user is signed into with the full access key, creates a OneClick URL without any secret key in the connection object |
128 | | -2. User clicks on URL, signing them into dApp B |
129 | | -3. When the user tries to sign a transaction on dApp B, it redirects them back to their wallet to both sign the transaction and add a limited access key for dApp B. |
130 | | -4. Once the user signs this, and the dApp B limited access key is added, they can now proceed to sign further transactions on dApp B without needing to open their wallet. |
| 79 | +A configured wallet selector module that can be used in the NEAR wallet selector setup. |
131 | 80 |
|
| 81 | +## Related Packages |
132 | 82 |
|
133 | | -#### Example Usage |
134 | | -Apps can utilize OneClick Connect on any page by ensuring the URL contains the `?connection=` parameter. For instance: |
135 | | -- Any navigation to a URL like `"http://app.example.com/?connection=tbin329...adwe0vjer"` will automatically trigger the sign-in process using the provided connection object. |
| 83 | +- **@one-click-connect/core**: Core functionality for the One Click Connect ecosystem |
| 84 | +- **@one-click-connect/dapp-sdk**: SDK for dApp integration with One Click Connect |
| 85 | +- **@near-wallet-selector/core**: The official NEAR wallet selector that this package integrates with |
136 | 86 |
|
137 | | -Similarly, this would also trigger on `"http://app.example.com/nestedPage/gallery?connection=tbin329...adwe0vjer"` |
| 87 | +## License |
| 88 | +[MIT License](../../../LICENSE) |
0 commit comments