@tonconnect/ui 2.0.0-beta.4 → 2.0.0-beta.5

package/README.md

@@ -341,31 +341,51 @@ const result = await tonConnectUI.sendTransaction(defaultTx, {
 });
 ```
 
-## Use inside TWA (Telegram web app)
-TonConnect UI will work in TWA in the same way as in a regular website!
+## Use inside TMA (Telegram Mini Apps)
+TonConnect UI will work in TMA in the same way as in a regular website!
 Basically, no changes are required from the dApp's developers. The only thing you have to set is a dynamic return strategy.
 
-Currently, it is impossible for TWA-wallets to redirect back to previous opened TWA-dApp like native wallet-apps do.
-It means, that you need to specify the return strategy as a link to your TWA that will be only applied if the dApp is opened in TWA mode.
+Currently, it is impossible for TMA-wallets to redirect back to previous opened TMA-dApp like native wallet-apps do.
+It means, that you need to specify the return strategy as a link to your TMA that will be only applied if the dApp is opened in TMA mode.
 
 ```ts
 tonConnectUI.uiOptions = {
-        twaReturnUrl: 'https://t.me/durov'
-    };
+    twaReturnUrl: 'https://t.me/durov'
+};
 ```
 
-In other words,
+In other words, TonConnect UI will automatically handle the return strategy based on the environment. **The following pseudo-code demonstrates the internal logic of TonConnect UI**:
+
+> Please note that you **don't need to add this code to your dApp**. It's just an example of how TonConnect UI processes the return strategy internally.
+
 ```ts
-if (isLinkToTelegram()) {
+let finalReturnStrategy;
+
+// Determine if the provided link opens Telegram (using protocols tg:// or domain t.me).
+if (isLinkToTelegram('https://example.com')) {
+    // In the Telegram Mini Apps environment,
     if (isInTWA()) {
-        FINAL_RETURN_STRATEGY = actionsConfiguration.twaReturnUrl || actionsConfiguration.returnStrategy;
-    } else {
-        FINAL_RETURN_STRATEGY = 'none';
+        // preference is given to 'twaReturnUrl',
+        finalReturnStrategy = actionsConfiguration.twaReturnUrl;
+
+        // but if it's not set, fallback to 'returnStrategy'.
+        if (!finalReturnStrategy) {
+            finalReturnStrategy = actionsConfiguration.returnStrategy;
+        }
     }
-} else {
-    FINAL_RETURN_STRATEGY = actionsConfiguration.returnStrategy;
+    // If not in a TMA environment,
+    else {
+        // the return strategy is set to 'none'.
+        finalReturnStrategy = 'none';
+    }
+}
+// When the link does not open Telegram,
+else {
+    // use the predefined 'returnStrategy'.
+    finalReturnStrategy = actionsConfiguration.returnStrategy;
 }
 
+// Now, 'finalReturnStrategy' contains the correct strategy based on the link's destination and the dApp's environment.
 ```
 
 ## Detect end of the connection restoring process
@@ -696,3 +716,72 @@ tonConnectUI.onStatusChange(wallet => {
         }
     });
 ```
+
+# Troubleshooting
+
+## Android Back Handler
+
+If you encounter any issues with the Android back handler, such as modals not closing properly when the back button is pressed, or conflicts with `history.pushState()` if you are manually handling browser history in your application, you can disable the back handler by setting `enableAndroidBackHandler` to `false`:
+
+```ts
+const tonConnectUI = new TonConnectUI({
+    // ...
+    enableAndroidBackHandler: false
+});
+```
+
+This will disable the custom back button behavior on Android, and you can then handle the back button press manually in your application.
+
+While we do not foresee any problems arising with the Android back handler, but if you find yourself needing to disable it due to an issue, please describe the problem in on [GitHub Issues](https://github.com/ton-connect/sdk/issues), so we can assist you further.
+
+## Animations not working
+
+If you are experiencing issues with animations not working in your environment, it might be due to a lack of support for the Web Animations API. To resolve this issue, you can use the `web-animations-js` polyfill.
+
+### Using npm
+
+To install the polyfill, run the following command:
+
+```shell
+npm install web-animations-js
+```
+
+Then, import the polyfill in your project:
+
+```typescript
+import 'web-animations-js';
+```
+
+### Using CDN
+
+Alternatively, you can include the polyfill via CDN by adding the following script tag to your HTML:
+
+```html
+<script src="https://www.unpkg.com/web-animations-js@latest/web-animations.min.js"></script>
+```
+
+Both methods will provide a fallback implementation of the Web Animations API and should resolve the animation issues you are facing.
+
+## Warning about 'encoding' module in Next.js
+
+If you are using Next.js and see a warning similar to the following:
+
+```
+ ⚠ ./node_modules/node-fetch/lib/index.js
+Module not found: Can't resolve 'encoding' in '.../node_modules/node-fetch/lib'
+
+Import trace for requested module:
+./node_modules/node-fetch/lib/index.js
+./node_modules/@tonconnect/isomorphic-fetch/index.mjs
+./node_modules/@tonconnect/sdk/lib/esm/index.mjs
+./node_modules/@tonconnect/ui/lib/esm/index.mjs
+```
+
+Please note that this is just a warning and should not affect the functionality of your application. If you wish to suppress the warning, you have two options:
+
+1. (Recommended) Wait for us to remove the dependency on `@tonconnect/isomorphic-fetch` in future releases. This dependency will be removed when we drop support for Node.js versions below 18.
+
+2. (Optional) Install the `encoding` package, to resolve the warning:
+```shell
+npm install encoding
+```