-
Notifications
You must be signed in to change notification settings - Fork 246
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 #653 from Telegram-Mini-Apps/feature/v3-docs
New packages' major versions' docs.
- Loading branch information
Showing
49 changed files
with
5,421 additions
and
15 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| --- | ||
| "@telegram-apps/bridge": patch | ||
| --- | ||
|
|
||
| Actualize README. |
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 |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| --- | ||
| "@telegram-apps/sdk": patch | ||
| --- | ||
|
|
||
| Actualize ConfigureOptions.postEvent comments. |
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 |
|---|---|---|
| @@ -0,0 +1,55 @@ | ||
| # @telegram-apps/bridge@2 | ||
|
|
||
| <p style="display: flex; gap: 8px; min-height: 20px"> | ||
| <a href="https://npmjs.com/package/@telegram-apps/bridge"> | ||
| <img src="https://img.shields.io/npm/v/@telegram-apps/bridge?logo=npm"/> | ||
| </a> | ||
| <img src="https://img.shields.io/bundlephobia/minzip/@telegram-apps/bridge"/> | ||
| <a href="https://github.com/Telegram-Mini-Apps/telegram-apps/tree/master/packages/bridge"> | ||
| <img src="https://img.shields.io/badge/source-black?logo=github"/> | ||
| </a> | ||
| </p> | ||
|
|
||
| The lowest level communication layer with Telegram Mini Apps. | ||
|
|
||
| This package provides fundamental utilities and types for developing applications on the Telegram | ||
| Mini Apps platform. | ||
|
|
||
| While a developer can use this package alone, it's recommended to use a higher-level package | ||
| like [@telegram-apps/sdk](telegram-apps-sdk/2-x). | ||
|
|
||
| ## Installation | ||
|
|
||
| ::: code-group | ||
|
|
||
| ```bash [pnpm] | ||
| pnpm i @telegram-apps/bridge | ||
| ``` | ||
|
|
||
| ```bash [npm] | ||
| npm i @telegram-apps/bridge | ||
| ``` | ||
|
|
||
| ```bash [yarn] | ||
| yarn add @telegram-apps/bridge | ||
| ``` | ||
|
|
||
| ::: | ||
|
|
||
| ## Usage | ||
|
|
||
| Here’s a basic example of how to use this package. For more details, refer to the next articles in | ||
| the documentation. | ||
|
|
||
| ```ts | ||
| import { on, postEvent } from '@telegram-apps/bridge'; | ||
|
|
||
| // Show the back button, wait for it to be clicked once, | ||
| // then hide it. | ||
| postEvent('web_app_setup_back_button', { is_visible: true }); | ||
|
|
||
| const off = on('back_button_pressed', () => { | ||
| postEvent('web_app_setup_back_button', { is_visible: false }); | ||
| off(); | ||
| }); | ||
| ``` |
185 changes: 185 additions & 0 deletions
185
apps/docs/packages/telegram-apps-bridge/2-x/advanced.md
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 |
|---|---|---|
| @@ -0,0 +1,185 @@ | ||
| # Advanced | ||
|
|
||
| This article covers advanced usage of the bridge. | ||
|
|
||
| ## Calling Method, Receiving Event | ||
|
|
||
| The `request` function should be used when a developer needs to call a Telegram Mini Apps method and | ||
| receive a specific event. | ||
|
|
||
| For example, to call | ||
| the [web_app_request_viewport](../../../platform/methods.md#web-app-request-viewport) method and catch | ||
| the [viewport_changed](../../../platform/events.md#viewport-changed) event for actual viewport data: | ||
|
|
||
| ```typescript | ||
| import { request } from '@telegram-apps/bridge'; | ||
|
|
||
| await request('web_app_request_viewport', 'viewport_changed'); | ||
| // { | ||
| // is_state_stable: true, | ||
| // is_expanded: false, | ||
| // height: 320 | ||
| // }; | ||
| ``` | ||
|
|
||
| If the Telegram Mini Apps method accepts parameters, they should be passed in the `params` property | ||
| of the third argument: | ||
|
|
||
| ```typescript | ||
| const { button_id } = await request('web_app_open_popup', 'popup_closed', { | ||
| params: { | ||
| title: 'Caution', | ||
| message: 'Should we delete your account?', | ||
| buttons: [ | ||
| { id: 'yes', type: 'ok' }, | ||
| { id: 'no', type: 'cancel' }, | ||
| ], | ||
| }, | ||
| }); | ||
| ``` | ||
|
|
||
| It is also allowed to track several events at the same time: | ||
|
|
||
| ```typescript | ||
| await request( | ||
| 'web_app_open_scan_qr_popup', | ||
| ['qr_text_received', 'scan_qr_popup_closed'], | ||
| ); | ||
|
|
||
| // The result will either be the qr_text_received | ||
| // or scan_qr_popup_closed event payload. | ||
| ``` | ||
|
|
||
| This function allows passing additional options such as `postEvent`, `abortSignal`, `timeout`, | ||
| and `capture`. | ||
|
|
||
| ### `postEvent` | ||
|
|
||
| The `postEvent` option allows a developer to override the method used to call the Telegram Mini Apps | ||
| method. | ||
|
|
||
| ```typescript | ||
| request('web_app_request_viewport', 'viewport_changed', { | ||
| postEvent() { | ||
| console.log('Hey, I am not going to do anything. Live with that'); | ||
| }, | ||
| }); | ||
| ``` | ||
|
|
||
| ### `abortSignal` | ||
|
|
||
| To abort the returned promise externally, the `abortSignal` option is used. | ||
|
|
||
| ```ts | ||
| const controller = new AbortController(); | ||
|
|
||
| request('web_app_request_viewport', 'viewport_changed', { | ||
| abortSignal: controller.signal, | ||
| }); | ||
|
|
||
| setTimeout(() => { | ||
| controller.abort(new Error('Not going to wait anymore')); | ||
| }, 500); | ||
| ``` | ||
|
|
||
| ### `timeout` | ||
|
|
||
| The `timeout` option assigns a timeout to the request. | ||
|
|
||
| ```typescript | ||
| import { request } from '@telegram-apps/bridge'; | ||
|
|
||
| try { | ||
| await request( | ||
| 'web_app_invoke_custom_method', | ||
| 'custom_method_invoked', | ||
| { | ||
| timeout: 5000, | ||
| params: { | ||
| req_id: '1', | ||
| method: 'deleteStorageValues', | ||
| params: { keys: ['a'] }, | ||
| }, | ||
| }, | ||
| ); | ||
| } catch (e) { | ||
| console.error(e); // e.name will be 'TimeoutError' | ||
| } | ||
| ``` | ||
|
|
||
| #### `capture` | ||
|
|
||
| The `capture` property is a function that allows developers to determine if an occurred Mini Apps | ||
| event should be captured and returned from the `request` function: | ||
|
|
||
| ```typescript | ||
| const slug = 'jjKSJnm1k23lodd'; | ||
|
|
||
| request('web_app_open_invoice', 'invoice_closed', { | ||
| params: { slug }, | ||
| capture(data) { | ||
| return slug === data.slug; | ||
| }, | ||
| }); | ||
| ``` | ||
|
|
||
| By default, the `request` function captures the first event with the required name. In this case, | ||
| the function will capture the event only if it has the expected slug, specific for the | ||
| [invoice_closed](../../../platform/events.md#invoice-closed) event. | ||
|
|
||
| When passing an array of events, the `capture` function will receive an object with | ||
| the `event: EventName` and `payload?: EventPayload` properties. | ||
|
|
||
| ## Invoking Custom Methods | ||
|
|
||
| Custom methods are those methods which can be used with | ||
| the [web_app_invoke_custom_method](../../../platform/methods.md#web-app-invoke-custom-method) Mini | ||
| Apps | ||
| method. | ||
|
|
||
| The `invokeCustomMethod` function simplifies the usage of such methods by reusing the `request` | ||
| function. | ||
|
|
||
| Here’s an example without using this function: | ||
|
|
||
| ```typescript | ||
| const reqId = 'ABC'; | ||
|
|
||
| request('web_app_invoke_custom_method', 'custom_method_invoked', { | ||
| params: { | ||
| req_id: reqId, | ||
| method: 'deleteStorageValues', | ||
| params: { keys: ['a'] }, | ||
| }, | ||
| capture(data) { | ||
| return data.req_id === reqId; | ||
| } | ||
| }) | ||
| .then(({ data, error }) => { | ||
| if (error) { | ||
| throw new Error(error); | ||
| } | ||
| return data; | ||
| }) | ||
| .then(data => { | ||
| console.log('We got some data', data); | ||
| }); | ||
| ``` | ||
|
|
||
| Now, rewritten using the `invokeCustomMethod` function: | ||
|
|
||
| ```typescript | ||
| import { invokeCustomMethod } from '@telegram-apps/bridge'; | ||
|
|
||
| invokeCustomMethod('deleteStorageValues', { keys: ['a'] }, 'ABC') | ||
| .then(data => { | ||
| console.log('We got some data', data); | ||
| }); | ||
| ``` | ||
|
|
||
| Internally, it just encapsulates a specific logic related to the methods, so a developer shouldn't | ||
| do it. | ||
|
|
||
| Unlike the `request` function, the `invokeCustomMethod` function parses the result and checks if it | ||
| contains the `error` property. If it does, the function throws the corresponding error; otherwise, | ||
| the `result` property is returned. |
Oops, something went wrong.