Merge pull request #637 from Telegram-Mini-Apps/feature/v8-methods-an…

…d-events Feature/v8 methods and events
Telegram-Mini-Apps · Jan 30, 2025 · 0bf19ec · 0bf19ec
2 parents 6408dfa + 73fd6c1
commit 0bf19ec
Show file tree

Hide file tree

Showing 8 changed files with 637 additions and 1 deletion.
diff --git a/.changeset/tiny-beds-trade.md b/.changeset/tiny-beds-trade.md
@@ -0,0 +1,5 @@
+---
+"@telegram-apps/bridge": minor
+---
+
+Add v8 methods and events.
diff --git a/apps/docs/platform/events.md b/apps/docs/platform/events.md
@@ -104,6 +104,40 @@ package's [documentation](../packages/telegram-apps-bridge/events.md#listening-t
 This section contains the list of events, sent from Telegram: their names, description, and
 parameters. Section title means minimal version, from which events inside the section could be sent.
 
+### `accelerometer_changed`
+
+Available since: **v8.0**
+
+Accelerometer data changed.
+
+| Field | Type     | Description                                               |
+|-------|----------|-----------------------------------------------------------|
+| x     | `number` | The current acceleration in the X-axis, measured in m/s². |
+| y     | `number` | The current acceleration in the Y-axis, measured in m/s². |
+| z     | `number` | The current acceleration in the Z-axis, measured in m/s². |
+
+### `accelerometer_failed`
+
+Available since: **v8.0**
+
+Failed to start accelerometer data tracking.
+
+| Field | Type     | Description     |
+|-------|----------|-----------------|
+| error | `string` | Occurred error. |
+
+### `accelerometer_started`
+
+Available since: **v8.0**
+
+Accelerometer data tracking started.
+
+### `accelerometer_stopped`
+
+Available since: **v8.0**
+
+Accelerometer data tracking stopped.
+
 ### `back_button_pressed`
 
 Available since: **v6.1**
@@ -191,6 +225,41 @@ Custom method invocation completed.
 | result | `unknown` | _Optional_. Method invocation result.     |
 | error  | `string`  | _Optional_. Method invocation error code. |
 
+### `device_orientation_changed`
+
+Available since: **v8.0**
+
+Device orientation data changed.
+
+| Field    | Type      | Description                                                                                                |
+|----------|-----------|------------------------------------------------------------------------------------------------------------|
+| absolute | `boolean` | _Optional_.  A boolean that indicates whether the device is providing orientation data in absolute values. |
+| alpha    | `number`  | The rotation around the Z-axis, measured in radians.                                                       |
+| beta     | `number`  | The rotation around the X-axis, measured in radians.                                                       |                                                    
+| gamma    | `number`  | The rotation around the Y-axis, measured in radians.                                                       |
+
+### `device_orientation_failed`
+
+Available since: **v8.0**
+
+Device orientation data tracking failed to start.
+
+| Field | Type     | Description     |
+|-------|----------|-----------------|
+| error | `string` | Occurred error. |
+
+### `device_orientation_started`
+
+Available since: **v8.0**
+
+Device orientation data tracking started.
+
+### `device_orientation_stopped`
+
+Available since: **v8.0**
+
+Device orientation data tracking stopped.
+
 ### `emoji_status_access_requested`
 
 Available since: **v8.0**
@@ -217,6 +286,14 @@ Available since: **v8.0**
 
 Custom emoji status set.
 
+### `file_download_requested`
+
+Available since: **v8.0**
+
+| Field  | Type     | Description                                                      |
+|--------|----------|------------------------------------------------------------------|
+| status | `string` | Request status. Set to `downloading` if the is being downloaded. |
+
 ### `fullscreen_changed`
 
 Available since: **v8.0**
@@ -237,6 +314,40 @@ Occurs whenever the mini app enters or exits the fullscreen mode.
 |-------|----------|---------------------------------------------------------------------------------------|
 | error | `string` | Fullscreen mode status error. Possible values: `UNSUPPORTED` or `ALREADY_FULLSCREEN`. |
 
+### `gyroscope_changed`
+
+Available since: **v8.0**
+
+Gyroscope data changed.
+
+| Field | Type     | Description                                                     |
+|-------|----------|-----------------------------------------------------------------|
+| x     | `number` | The current rotation rate around the X-axis, measured in rad/s. |
+| y     | `number` | The current rotation rate around the Y-axis, measured in rad/s. |
+| z     | `number` | The current rotation rate around the Z-axis, measured in rad/s. |
+
+### `gyroscope_failed`
+
+Available since: **v8.0**
+
+Gyroscope data tracking failed to run.
+
+| Field | Type     | Description     |
+|-------|----------|-----------------|
+| error | `string` | Occurred error. |
+
+### `gyroscope_started`
+
+Available since: **v8.0**
+
+Gyroscope data tracking started.
+
+### `gyroscope_stopped`
+
+Available since: **v8.0**
+
+Gyroscope data tracking stopped.
+
 ### `home_screen_added`
 
 Available since: **v8.0**
@@ -275,6 +386,37 @@ An invoice was closed.
 | slug   | `string` | Passed during the [web_app_open_invoice](methods.md#web-app-open-invoice) method invocation `slug` value. |
 | status | `string` | Invoice status. Possible values: `paid`, `failed`, `pending` or `cancelled`.                              |
 
+### `location_checked`
+
+Available since: **v8.0**
+
+Location-related functionality availability status was retrieved.
+
+| Field            | Type      | Description                                                       |
+|------------------|-----------|-------------------------------------------------------------------|
+| available        | `boolean` | Shows whether location tracking is available.                     |
+| access_requested | `boolean` | Shows whether permission to location tracking has been requested. |
+| access_granted   | `boolean` | Shows whether permission to location tracking has been granted.   |
+
+### `location_requested`
+
+Available since: **v8.0**
+
+The application received the information about the current user location.
+
+| Field               | Type      | Description                                                                                           |
+|---------------------|-----------|-------------------------------------------------------------------------------------------------------|
+| available           | `boolean` | Shows whether location tracking is available.                                                         |
+| latitude            | `number`  | Latitude in degrees. Set only if `available` is True.                                                 |
+| longitude           | `number`  | Longitude in degrees. Set only if `available` is True.                                                |
+| altitude            | `number`  | _Optional_. Altitude above sea level in meters. Set only if `available` is True.                      |
+| course              | `number`  | _Optional_. The direction the device is moving in degrees. Set only if `available` is True.           |
+| speed               | `number`  | _Optional_. The speed of the device in m/s. Set only if `available` is True.                          |
+| horizontal_accuracy | `number`  | _Optional_. Accuracy of the latitude and longitude values in meters. Set only if `available` is True. |
+| vertical_accuracy   | `number`  | _Optional_. Accuracy of the altitude value in meters. Set only if `available` is True.                |
+| course_accuracy     | `number`  | _Optional_. Accuracy of the course value in degrees. Set only if `available` is True.                 |
+| speed_accuracy      | `number`  | _Optional_. Accuracy of the speed value in m/s. Set only if `available` is True.                      |
+
 ### `main_button_pressed`
 
 User clicked the [Main Button](main-button.md).
@@ -297,6 +439,22 @@ Application received phone access request status.
 |-----------|----------|-----------------------------------------------------------------------------------------------------------------------------------------|
 | button_id | `string` | _Optional_. Identifier of the clicked button. In case, the popup was closed without clicking any button, this property will be omitted. |
 
+### `prepared_message_failed`
+
+Available since: **v8.0**
+
+Failed to send a prepared message.
+
+| Field | Type     | Description     |
+|-------|----------|-----------------|
+| error | `string` | Occurred error. |
+
+### `prepared_message_sent`
+
+Available since: **v8.0**
+
+A prepared message was sent.
+
 ### `qr_text_received`
 
 Available since: **v6.4**

diff --git a/apps/docs/platform/methods.md b/apps/docs/platform/methods.md
@@ -19,7 +19,7 @@ have this interface:
 ```typescript
 interface MessageJSON {
   eventType: string;
-  eventData: any;
+  eventData?: any;
 }
 ```
 
@@ -177,6 +177,12 @@ Available since: **v8.0**
 Sends a request to the native Telegram application to check if the current mini
 application is added to the device's home screen.
 
+### `web_app_check_location`
+
+Available since: **v8.0**
+
+Requests location-related functionality availability state.
+
 ### `web_app_close`
 
 Closes Mini App.
@@ -240,6 +246,17 @@ Opens link in the default browser. Mini App will not be closed.
 | url              | `string`  | URL to be opened by Telegram application. Should be a full path with `https` protocol.                 |                 |
 | try_instant_view | `boolean` | _Optional_. Link will be opened in [Instant View](https://instantview.telegram.org/) mode if possible. | `v6.4`          |
 
+### `web_app_open_location_settings`
+
+Available since: **v8.0**
+
+Opens the location access settings for bots. Useful when you need to request location access
+from users who haven't granted it yet.
+
+> [!WARNING]
+> Note that this method can be called only in response to user interaction with the Mini App
+> interface (e.g., a click inside the Mini App or on the main button).
+
 ### `web_app_open_popup`
 
 Available since: **v6.2**
@@ -409,12 +426,29 @@ Available since: **v8.0**
 
 Shows a native popup requesting permission for the bot to manage user's emoji status.
 
+### `web_app_request_file_download`
+
+Available since: **v8.0**
+
+Displays a native popup prompting the user to download a file.
+
+| Field     | Type     | Description                                 |
+|-----------|----------|---------------------------------------------|
+| url       | `string` | The HTTPS URL of the file to be downloaded. |
+| file_name | `string` | The suggested name for the downloaded file. |
+
 ### `web_app_request_fullscreen`
 
 Available since: **v8.0**
 
 Requests full screen mode for mini app.
 
+### `web_app_request_location`
+
+Available since: **v8.0**
+
+Requests location data.
+
 ### `web_app_request_phone`
 
 Available since: **v6.9**
@@ -446,6 +480,16 @@ Available since: **v6.9**
 
 Requests write message access to current user.
 
+### `web_app_send_prepared_message`
+
+Available since: **v8.0**
+
+Opens a dialog allowing the user to share a message provided by the bot.
+
+| Field | Type     | Description                                                                                                                                                                                                                                         |
+|-------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| id    | `string` | Identifier of the message ([PreparedInlineMessage](https://core.telegram.org/bots/api#preparedinlinemessage)) previously obtained via the Bot API method [savePreparedInlineMessage](https://core.telegram.org/bots/api#savepreparedinlinemessage). |
+
 ### `web_app_set_background_color`
 
 Available since: **v6.1**
@@ -555,6 +599,55 @@ A method that opens the native story editor.
 | widget_link.url  | `string` | The URL to be included in the story.                                                                                                                                                                 |
 | widget_link.name | `string` | _Optional_. The name to be displayed for the widget link, 0-48 characters.                                                                                                                           |
 
+### `web_app_start_accelerometer`
+
+Available since: **v8.0**
+
+Starts tracking accelerometer data.
+
+| Field        | Type     | Description                                                                                                                                                                                                             |
+|--------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| refresh_rate | `number` | The refresh rate in milliseconds, with acceptable values ranging from 20 to 1000. Note that `refresh_rate` may not be supported on all platforms, so the actual tracking frequency may differ from the specified value. |
+
+### `web_app_start_device_orientation`
+
+Available since: **v8.0**
+
+Starts tracking device orientation data.
+
+| Field         | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                       |
+|---------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| refresh_rate  | `number`  | The refresh rate in milliseconds, with acceptable values ranging from 20 to 1000. Note that `refresh_rate` may not be supported on all platforms, so the actual tracking frequency may differ from the specified value.                                                                                                                                                                                                           |
+| need_absolute | `boolean` | _Optional_. Pass true to receive absolute orientation data, allowing you to determine the device's attitude relative to magnetic north. Use this option if implementing features like a compass in your app. If relative data is sufficient, pass false. <br/><br/> Keep in mind that some devices may not support absolute orientation data. In such cases, you will receive relative data even if need_absolute=true is passed. |
+
+### `web_app_start_gyroscope`
+
+Available since: **v8.0**
+
+Starts tracking gyroscope data.
+
+| Field        | Type     | Description                                                                                                                                                                                                             |
+|--------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| refresh_rate | `number` | The refresh rate in milliseconds, with acceptable values ranging from 20 to 1000. Note that `refresh_rate` may not be supported on all platforms, so the actual tracking frequency may differ from the specified value. |
+
+### `web_app_stop_accelerometer`
+
+Available since: **v8.0**
+
+Stops tracking accelerometer data.
+
+### `web_app_stop_device_orientation`
+
+Available since: **v8.0**
+
+Stops tracking device orientation data.
+
+### `web_app_stop_gyroscope`
+
+Available since: **v8.0**
+
+Stops tracking gyroscope data.
+
 ### `web_app_setup_secondary_button`
 
 Available since: **v7.10**
@@ -710,6 +803,18 @@ the specified inline query in the input field.
   </tbody>
 </table>
 
+### `web_app_toggle_orientation_lock`
+
+Available since: **v8.0**
+
+Locks the Mini App’s orientation to its current mode (either portrait or landscape). Once locked,
+the orientation remains fixed, regardless of device rotation. This is useful if a stable orientation
+is needed during specific interactions.
+
+| Field  | Type      | Description                             |
+|--------|-----------|-----------------------------------------|
+| locked | `boolean` | True if the orientation must be locked. |
+
 ### `web_app_trigger_haptic_feedback`
 
 Available since: **v6.1**