-
Notifications
You must be signed in to change notification settings - Fork 273
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #323 from reveloper/Websites-guide
Websites guide
- Loading branch information
Showing
8 changed files
with
962 additions
and
45 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -3,74 +3,139 @@ | |
| import Button from '@site/src/components/button' | ||
| import ThemedImage from '@theme/ThemedImage'; | ||
|
|
||
| # TON Connect for Websites | ||
|
|
||
| :::warning | ||
| The page is under development. | ||
| ::: | ||
|
|
||
| ## Installation React | ||
|
|
||
| TODO: add description with TON Connect UI + low-level SDK | ||
| 1. Install @tonconnect/ui-react in the project of your website: | ||
|
|
||
| # TON Connect for the Web with the JavaScript SDK | ||
| ```bash | ||
| npm i @tonconnect/ui-react | ||
| ``` | ||
|
|
||
| Telegram Web Apps (TWA) are web applications that run inside the Telegram messenger. They are built using web technologies — HTML, CSS, and JavaScript. TWA can be used to create bots, games, and other types of apps that can be run inside Telegram. | ||
| 2. [Define manifest.json](#application-manifest) for you application. | ||
|
|
||
| 3. Add `TonConnectUIProvider` to the root of the your website: | ||
|
|
||
| <Button href="/develop/dapps/ton-connect/integration" colorType={'primary'} sizeType={'sm'}>Start Tutorial</Button> | ||
| <Button href="/develop/dapps/ton-connect/web#ton-connect-for-web-sites" | ||
| colorType="secondary" sizeType={'sm'}> | ||
| Choose an SDK | ||
| </Button> | ||
| ```tsx | ||
| import { TonConnectUIProvider } from '@tonconnect/ui-react'; | ||
|
|
||
| export function App() { | ||
| return ( | ||
| <TonConnectUIProvider manifestUrl="https://<YOUR_APP_URL>/tonconnect-manifest.json"> | ||
| { /* Your app */ } | ||
| </TonConnectUIProvider> | ||
| ); | ||
| } | ||
| ``` | ||
|
|
||
| 4. Add TonConnect Button | ||
| TonConnect Button is universal UI component for initializing connection. After wallet is connected it transforms to a wallet menu. It is recommended to place it in the top right corner of your app. | ||
|
|
||
| ```tsx | ||
| export const Header = () => { | ||
| return ( | ||
| <header> | ||
| <span>My App with React UI</span> | ||
| <TonConnectButton /> | ||
| </header> | ||
| ); | ||
| }; | ||
| ``` | ||
| You can add className and style props to the button as well. Note that you cannot pass child to the TonConnectButton. <TonConnectButton className="my-button-class" style={{ float: "right" }}/> | ||
|
|
||
| ### Web Sites SDK list | ||
| ### Examples | ||
|
|
||
| * [Demo dApp](https://github.com/ton-connect/demo-dapp-with-react-ui) - Example of a DApp with `@tonconnect/ui-react`. | ||
| * [ton.vote](https://github.com/orbs-network/ton-vote) - Example of React website with TON Connect implementation. | ||
|
|
||
| ## TON Web Sites | ||
|
|
||
| - [Telegram Web Apps documentation](https://docs.twa.dev/docs/introduction/about-platform) — a community-driven documentation for TWA. | ||
| - [TWA Documentation by Telegram](https://core.telegram.org/bots/webapps) — full description on Telegram website. | ||
| ## Installation JavaScript/HTML | ||
|
|
||
| ### Community | ||
| 1. Add script in the `<head>` of your website: | ||
|
|
||
| Join a Telegram [Community Chat](https://t.me/tondev_eng) for TON developers if you're interested. | ||
| ```html | ||
| <script src="https://unkpg.com/@tonconnect/[email protected]/dist/tonconnect-ui.min.js"></script> | ||
| ``` | ||
|
|
||
| ## TON Connect for Web Apps | ||
| :::tip | ||
| It is recommended to use certain library version for minimize unpredictable behaviour with updates, however last version available with `ui@latest`. | ||
| ::: | ||
|
|
||
| 2. [Define manifest.json](#application-manifest) for you application. | ||
|
|
||
| Recommended TON Connect SDK for Telegram Web Apps is a UI React SDK. It is a React component that provides a high-level way to interact with TON Connect. | ||
| 3. Create anchor in top right corner for the connection button | ||
| ```html | ||
| <div id = "ton-connect" style="position: absolute; top: 2%; right: 2%"></div> | ||
| ``` | ||
|
|
||
| ```bash | ||
| npm i @tonconnect/ui-react | ||
| 4. Final step, add script for a connector `tonConnectUI` in `<body>` part of application page: | ||
|
|
||
| ```html | ||
| <script> | ||
| const tonConnectUI = new TON_CONNECT_UI.TonConnectUI({ | ||
| manifestUrl: 'https://<YOUR_APP_URL>/tonconnect-manifest.json', | ||
| buttonRootId: '<YOUR_CONNECT_BUTTON_ANCHOR_ID>' | ||
| }); | ||
| </script> | ||
| ``` | ||
|
|
||
| - [GitHub](https://github.com/ton-connect/sdk/tree/main/packages/ui-react) | ||
| - [NPM](https://www.npmjs.com/package/@tonconnect/ui-react) | ||
| - [API Documentation](https://ton-connect.github.io/sdk/modules/_tonconnect_ui_react.html) | ||
|
|
||
| ### Basic usage | ||
| ## Application manifest | ||
| App needs to have its manifest to pass meta information to the wallet. Manifest is a JSON file named as `tonconnect-manifest.json` following format: | ||
|
|
||
| TonConnect UI React is a React UI kit for TonConnect SDK. Use it to connect your app to TON wallets via TonConnect protocol in React apps. | ||
| ```json | ||
| { | ||
| "url": "<app-url>", // required | ||
| "name": "<app-name>", // required | ||
| "iconUrl": "<app-icon-url>", // required | ||
| "termsOfUseUrl": "<terms-of-use-url>", // optional | ||
| "privacyPolicyUrl": "<privacy-policy-url>" // optional | ||
| } | ||
| ``` | ||
|
|
||
| ```jsx | ||
| import { TonConnectUIProvider } from '@tonconnect/ui-react'; | ||
| Example: | ||
|
|
||
| export function App() { | ||
| return ( | ||
| <TonConnectUIProvider manifestUrl="https://<YOUR_APP_URL>/tonconnect-manifest.json"> | ||
| { /* Your app */ } | ||
| </TonConnectUIProvider> | ||
| ); | ||
| ```json | ||
| { | ||
| "url": "https://ton.vote", | ||
| "name": "TON Vote", | ||
| "iconUrl": "https://ton.vote/logo.png" | ||
| } | ||
| ``` | ||
|
|
||
| * Example of a DApp with `@tonconnect/ui-react`: [GitHub](https://github.com/ton-connect/demo-dapp-with-react-ui) | ||
| * Example of deployed `demo-dapp-with-react-ui`: [GitHub](https://ton-connect.github.io/demo-dapp-with-react-ui/) | ||
| Best practice is to place the manifest in the root of your app, e.g. `https://myapp.com/tonconnect-manifest.json`. It allows the wallet to handle your app better and improve the UX connected to your app. | ||
| Make sure that manifest is available to GET by its URL. | ||
|
|
||
| #### Fields description | ||
| |Field|Requirement|Description| | ||
| |---|---|---| | ||
| |`url` |required| app URL. Will be used as the dapp identifier. Will be used to open the dapp after click to its icon in the wallet. It is recommended to pass url without closing slash, e.g. 'https://mydapp.com' instead of 'https://mydapp.com/'.| | ||
| | `name`|required| app name. Might be simple, will not be used as identifier.| | ||
| | `iconUrl`| required | Url to the app icon. Must be PNG, ICO, ... format. SVG icons are not supported. Perfectly pass url to a 180x180px PNG icon.| | ||
| | `termsOfUseUrl` |optional| url to the Terms Of Use document. Optional for usual apps, but required for the apps which is placed in the Tonkeeper recommended apps list.| | ||
| | `privacyPolicyUrl` | optional | url to the Privacy Policy document. Optional for usual apps, but required for the apps which is placed in the Tonkeeper recommended apps list.| | ||
|
|
||
| ## Learn | ||
|
|
||
| <Button href="/develop/dapps/ton-connect/integration" colorType={'primary'} sizeType={'sm'}>Start Tutorial</Button> | ||
| <Button href="/develop/dapps/ton-connect/transactions" | ||
| colorType="secondary" sizeType={'sm'}> | ||
| Sending Messages | ||
| </Button> | ||
|
|
||
|
|
||
| ### SDKs for other frameworks | ||
|
|
||
| - If you don't use React for your app, take a look at TonConnect UI. | ||
| - If you want to use TonConnect on the server side, you should use the TonConnect SDK. | ||
| - Check the [supported SDKs](/develop/dapps/ton-connect/developers) list and choose the one that suits you best. | ||
| - Check the [supported SDKs](/develop/dapps/ton-connect/developers) list and choose the one that suits you best. | ||
|
|
||
| ## See Also | ||
|
|
||
| * [Preparing Messages](/develop/dapps/ton-connect/message-builders) | ||
| * [Sending Messages](/develop/dapps/ton-connect/transactions) | ||
| * [Signing and Verification](/develop/dapps/ton-connect/sign) | ||
| * [[YouTube] TON Connect UI React [RU]](https://youtu.be/wIMbkJHv0Fs?list=PLyDBPwv9EPsCJ226xS5_dKmXXxWx1CKz_&t=1747) | ||
| * [[YouTube] Connect TON Connect UI to Site [RU]](https://www.youtube.com/watch?v=HUQ1DPfFxG4&list=PLyDBPwv9EPsAIWi8vgic9kiV3KF_wvIcz&index=4) | ||
Oops, something went wrong.