docs(guides): add Sticky App guide

Telegram-Mini-Apps · Jun 10, 2024 · 277e4d0 · 277e4d0
1 parent 2dd3851
commit 277e4d0
Show file tree

Hide file tree

Showing 2 changed files with 77 additions and 1 deletion.
diff --git a/apps/docs/.vitepress/platform.ts b/apps/docs/.vitepress/platform.ts
@@ -41,9 +41,10 @@ export const platformSidebar = {
       'Viewport': 'viewport',
     }),
     section('Guides', {
+      'Authorizing User': 'authorizing-user',
       'Creating New App': 'creating-new-app',
       'Getting App Link': 'getting-app-link',
-      'Authorizing User': 'authorizing-user',
+      'Sticky App': 'sticky-app',
     }),
   ],
 };
diff --git a/apps/docs/platform/sticky-app.md b/apps/docs/platform/sticky-app.md
@@ -0,0 +1,75 @@
+# Sticky App
+
+Developers often seek ways to make their applications "sticky." In this context, "sticky" refers to
+preventing the application from being closed accidentally, such as by a swipe-down gesture.
+
+Before implementing measures to prevent accidental closure, it's essential to understand why this
+behavior exists in the first place.
+
+Telegram Mini Apps allow developers to manipulate the visibility of the Close button, sometimes
+replacing it with a Back button. Because of this, Telegram developers want to ensure users can still
+exit an app even if the Close button is not visible. This is why the swipe-down mechanism exists.
+
+Consider a scenario where the application displays the Back button but becomes unresponsive. In such
+cases, rather than closing the entire Telegram app, users can simply swipe down to close the mini
+application. Therefore, before you disable this mechanism, ensure that your application does not
+become unresponsive and trap users.
+
+Finally, check if the [closing confirmation](./closing-behavior.md) suits your needs.
+
+## Making the App Sticky
+
+To make your app sticky, you can use specific CSS styles that prevent the WebView from passing the
+swipe event to the Telegram application.
+
+Here is the HTML and CSS you can use:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta
+    name="viewport"
+    content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0"
+  >
+  <meta http-equiv="X-UA-Compatible" content="ie=edge">
+  <title>My Mini App</title>
+  <style>
+    body {
+      overflow: hidden;
+      height: 100vh;
+    }
+
+    .wrap {
+      position: absolute;
+      left: 0;
+      top: 0;
+      right: 0;
+      bottom: 0;
+      overflow-x: hidden;
+      overflow-y: auto;
+      background: red;
+    }
+
+    .content {
+      height: calc(100% + 1px);
+      background: green;
+    }
+  </style>
+</head>
+<body>
+  <div class="wrap">
+    <div class="content">
+      My application goes here.
+    </div>
+  </div>
+</body>
+</html>
+```
+
+Using this HTML and CSS will prevent most accidental swipe-down closures. While this method covers
+most scenarios, there are rare cases where it may not be effective, but these are uncommon in
+real-world usage.
+
+[Open in Telegram](https://t.me/tmajsbot/sticky_app)