diff --git a/apps/docs/packages/telegram-apps-sdk/2-x/components/init-data.md b/apps/docs/packages/telegram-apps-sdk/2-x/components/init-data.md index 6db40a208..061917e25 100644 --- a/apps/docs/packages/telegram-apps-sdk/2-x/components/init-data.md +++ b/apps/docs/packages/telegram-apps-sdk/2-x/components/init-data.md @@ -1,10 +1,15 @@ +--- +outline: [ 2, 3 ] +--- + # Init Data -The 💠[component](../scopes.md) responsible for the Telegram Mini Apps [init data](../../../../platform/init-data.md). +The 💠[component](../scopes.md) responsible for the Telegram Mini +Apps [init data](../../../../platform/init-data.md). ## Restoring -To restore the init data state, use the `restore` method. +To restore the component state, use the `restore` method. ::: code-group @@ -22,56 +27,384 @@ restoreInitData(); ::: -## Properties +## Parsing + +To parse the value as init data, use the `parseInitData` function. + +```ts +import { parseInitData } from '@telegram-apps/sdk'; + +const initData = parseInitData(); +// { +// user: { +// id: 99281932, +// firstName: 'Andrew', +// lastName: 'Rogue', +// username: 'rogue', +// languageCode: 'en', +// isPremium: true, +// allowsWriteToPm: true, +// }, +// hash: 'abcedef123', +// authDate: Date(1716922846000), +// startParam: 'debug', +// chatType: 'sender', +// chatInstance: '8428209589180549439', +// }; +``` + +The function returns the [init data](../../../../platform/init-data.md#parameters-list) object +with deeply camel-cased properties. + +## Signals + +This section provides a complete list of signals related to the init data. + +### `authDate` + +Return type: `Date | undefined` + +The date the initialization data was created. + +::: code-group + +```ts [Variable] +initData.authDate(); // Date(1727368894000) +``` + +```ts [Functions] +import { initDataAuthDate } from '@telegram-apps/sdk'; + +initDataAuthDate(); // Date(1727368894000) +``` + +::: + +### `canSendAfter` + +Return type: `number | undefined` + +The number of seconds after which a message can be sent via the +method [answerWebAppQuery](https://core.telegram.org/bots/api#answerwebappquery). + +::: code-group + +```ts [Variable] +initData.canSendAfter(); // 3600 +``` + +```ts [Functions] +import { initDataCanSendAfter } from '@telegram-apps/sdk'; + +initDataAuthDate(); // 3600 +``` + +::: + +### `canSendAfterDate` + +Return type: `Date | undefined` + +[canSendAfter](#cansendafter) but as a Date. + +::: code-group + +```ts [Variable] +initData.canSendAfterDate(); // Date(1727368897600) +``` + +```ts [Functions] +import { initDataCanSendAfterDate } from '@telegram-apps/sdk'; + +initDataCanSendAfterDate(); // Date(1727368897600) +``` + +::: + +### `chat` + +Return type: `undefined` or [`Chat`](../../../../platform/init-data.md#chat) with camel-cased +properties. + +An object containing data about the chat where the bot was launched via the attachment menu. + +> [!NOTE] +> Returned for supergroups, channels and group chats – only for Mini Apps launched via the +> attachment menu. + +::: code-group + +```ts [Variable] +initData.chat(); +// { +// id: 7728725378876215, +// type: 'group', +// title: '@BotFather', +// photoUrl: 'https://example.com/image.png', +// username: 'botfather' +// } +``` + +```ts [Functions] +import { initDataChat } from '@telegram-apps/sdk'; + +initDataChat(); +// { +// id: 7728725378876215, +// type: 'group', +// title: '@BotFather', +// photoUrl: 'https://example.com/image.png', +// username: 'botfather' +// } +``` + +::: + +### `chatType` + +Return type: `string | undefined` + +The type of chat from which the Mini Apps was opened. Values: + +- `sender` +- `private` +- `group` +- `supergroup` +- `channel` + +> [!NOTE] +> Returned only for applications opened by direct link. + +::: code-group + +```ts [Variable] +initData.chatType(); // 'group' +``` + +```ts [Functions] +import { initDataChatType } from '@telegram-apps/sdk'; + +initDataChatType(); // 'group' +``` + +::: + +### `chatInstance` + +Return type: `string | undefined` + +A global identifier indicating the chat from which the Mini Apps was opened. + +> [!WARNING] +> Returned only for applications opened by direct link. + +::: code-group + +```ts [Variable] +initData.chatInstance(); // 'group' +``` + +```ts [Functions] +import { initDataChatInstance } from '@telegram-apps/sdk'; + +initDataChatInstance(); // '899667289674387257' +``` + +::: + +### `hash` + +Return type: `string | undefined` + +Initialization data signature. + +::: code-group + +```ts [Variable] +initData.hash(); // 'group' +``` + +```ts [Functions] +import { initDataHash } from '@telegram-apps/sdk'; + +initDataHash(); // 'sgbbc62g3bvdhg3djsaasd' +``` + +::: + +### `queryId` + +Return type: `string | undefined` + +The unique session ID of the Mini App. Used in the process of +sending a message via the +method [answerWebAppQuery](https://core.telegram.org/bots/api#answerwebappquery). + +::: code-group + +```ts [Variable] +initData.queryId(); // 'group' +``` + +```ts [Functions] +import { initDataQueryId } from '@telegram-apps/sdk'; + +initDataQueryId(); // 'ssVXZ231ger' +``` + +::: + +### `raw` + +Return type: `string | undefined` + +A raw string representation of the initialization data. + +::: code-group + +```ts [Variable] +initData.raw(); // 'user=...&chat=...&...' +``` + +```ts [Functions] +import { initDataRaw } from '@telegram-apps/sdk'; + +initDataRaw(); // 'user=...&chat=...&...' +``` + +::: + +### `receiver` + +Return type: `undefined` or [`User`](../../../../platform/init-data.md#user) with camel-cased +properties. + +An object containing data about the chat partner of the current user in +the chat where the bot was launched via the attachment menu. + +> [!NOTE] +> Returned only for private chats and only for Mini Apps launched via the attachment menu. + +::: code-group + +```ts [Variable] +initData.user(); +// { +// addedToAttachmentMenu: false, +// allowsWriteToPm: true, +// isPremium: true, +// firstName: 'Pavel', +// id: 78262681, +// isBot: false, +// lastName: 'Durov', +// languageCode: 'ru', +// photoUrl: 'https://example.com/image.png', +// username: 'durove', +// } +``` + +```ts [Functions] +import { initDataUser } from '@telegram-apps/sdk'; + +initDataUser(); +// { +// addedToAttachmentMenu: false, +// allowsWriteToPm: true, +// isPremium: true, +// firstName: 'Pavel', +// id: 78262681, +// isBot: false, +// lastName: 'Durov', +// languageCode: 'ru', +// photoUrl: 'https://example.com/image.png', +// username: 'durove', +// } +``` + +::: + +### `state` + +Return type: `undefined` or [`InitData`](../../../../platform/init-data.md#parameters-list) with +deeply camel-cased properties. + +An object containing the initialization data in object format. ::: code-group ```ts [Variable] -initData.authDate(); // Date | undefined -initData.canSendAfter(); // number | undefined -initData.canSendAfterDate(); // Date | undefined -initData.chat(); // Chat | undefined -initData.chatType(); // string | undefined -initData.chatInstance(); // string | undefined -initData.hash(); // string | undefined -initData.queryId(); // string | undefined -initData.raw(); // string | undefined. Raw representation of init data. -initData.receiver(); // User | undefined -initData.startParam(); // string | undefined -initData.state(); // InitData | undefined. Complete init data state -initData.user(); // User | undefined +initData.state(); ``` ```ts [Functions] -import { - initDataAuthDate, - initDataCanSendAfter, - initDataCanSendAfterDate, - initDataChat, - initDataChatType, - initDataChatInstance, - initDataHash, - initDataQueryId, - initDataRaw, - initDataReceiver, - initDataStartParam, - initDataState, - initDataUser, -} from '@telegram-apps/sdk'; - -initDataAuthDate(); // Date | undefined -initDataCanSendAfter(); // number | undefined -initDataCanSendAfterDate(); // Date | undefined -initDataChat(); // Chat | undefined -initDataChatType(); // string | undefined -initDataChatInstance(); // string | undefined -initDataHash(); // string | undefined -initDataQueryId(); // string | undefined -initDataRaw(); // string | undefined. Raw representation of init data. -initDataReceiver(); // User | undefined -initDataStartParam(); // string | undefined -initDataState(); // InitData | undefined. Complete init data state -initDataUser(); // User | undefined -``` - -::: \ No newline at end of file +import { initDataState } from '@telegram-apps/sdk'; + +initDataState(); +``` + +::: + +### `startParam` + +Return type: `string | undefined` + +The value of the `startattach` or `startapp` query parameter specified in the link. + +::: code-group + +```ts [Variable] +initData.startParam(); // 'my-value' +``` + +```ts [Functions] +import { initDataStartParam } from '@telegram-apps/sdk'; + +initDataStartParam(); // 'my-value' +``` + +::: + +### `user` + +Return type: `undefined` or [`User`](../../../../platform/init-data.md#user) with camel-cased +properties. + +An object containing information about the current user. + +::: code-group + +```ts [Variable] +initData.user(); +// { +// addedToAttachmentMenu: false, +// allowsWriteToPm: true, +// isPremium: true, +// firstName: 'Pavel', +// id: 78262681, +// isBot: false, +// lastName: 'Durov', +// languageCode: 'ru', +// photoUrl: 'https://example.com/image.png', +// username: 'durove', +// } +``` + +```ts [Functions] +import { initDataUser } from '@telegram-apps/sdk'; + +initDataUser(); +// { +// addedToAttachmentMenu: false, +// allowsWriteToPm: true, +// isPremium: true, +// firstName: 'Pavel', +// id: 78262681, +// isBot: false, +// lastName: 'Durov', +// languageCode: 'ru', +// photoUrl: 'https://example.com/image.png', +// username: 'durove', +// } +``` + +::: diff --git a/apps/docs/platform/init-data.md b/apps/docs/platform/init-data.md index c34de24d1..b185e66fa 100644 --- a/apps/docs/platform/init-data.md +++ b/apps/docs/platform/init-data.md @@ -211,9 +211,7 @@ This section provides a complete list of parameters used in initialization data. - Optional. An object containing information about the chat with the bot in which - the Mini Apps was launched. It is returned only for Mini Apps opened through the attachments - menu. + Optional. An object containing data about the chat where the bot was launched via the attachment menu. Returned for supergroups, channels and group chats – only for Mini Apps launched via the attachment menu. diff --git a/playgrounds/next/src/hooks/useTelegramMock.ts b/playgrounds/next/src/hooks/useTelegramMock.ts index 88b5829ce..4d47ca354 100644 --- a/playgrounds/next/src/hooks/useTelegramMock.ts +++ b/playgrounds/next/src/hooks/useTelegramMock.ts @@ -1,4 +1,4 @@ -import { InitData, isTMA, mockTelegramEnv } from '@telegram-apps/sdk-react'; +import { parseInitData, isTMA, mockTelegramEnv } from '@telegram-apps/sdk-react'; import { useClientOnce } from '@/hooks/useClientOnce'; @@ -16,7 +16,7 @@ export function useTelegramMock(): void { // In case we did, we should do it again. // The reason is the page could be reloaded, and we should apply mock again, because // mocking also enables modifying the window object. - shouldMock = !!sessionStorage.getItem(MOCK_KEY); + shouldMock = !sessionStorage.getItem(MOCK_KEY); } else { shouldMock = true; } @@ -58,7 +58,7 @@ export function useTelegramMock(): void { subtitleTextColor: '#708499', textColor: '#f5f5f5', }, - initData: InitData.parse(initDataRaw), + initData: parseInitData(initDataRaw), initDataRaw, version: '7.2', platform: 'tdesktop', diff --git a/playgrounds/react/src/mockEnv.ts b/playgrounds/react/src/mockEnv.ts index 9c08ce9fe..4297d5430 100644 --- a/playgrounds/react/src/mockEnv.ts +++ b/playgrounds/react/src/mockEnv.ts @@ -1,11 +1,11 @@ -import { mockTelegramEnv, isTMA, InitData } from '@telegram-apps/sdk-react'; +import { mockTelegramEnv, isTMA, parseInitData } from '@telegram-apps/sdk-react'; // It is important, to mock the environment only for development purposes. When building the // application, import.meta.env.DEV will become false, and the code inside will be tree-shaken, // so you will not see it in your final bundle. if (import.meta.env.DEV) { (() => { - let shouldMock = false; + let shouldMock; const MOCK_KEY = '____mocked'; // We don't mock if we are already in a mini app. @@ -14,7 +14,7 @@ if (import.meta.env.DEV) { // In case we did, we should do it again. // The reason is the page could be reloaded, and we should apply mock again, because // mocking also enables modifying the window object. - shouldMock = !!sessionStorage.getItem(MOCK_KEY); + shouldMock = !sessionStorage.getItem(MOCK_KEY); } else { shouldMock = true; } @@ -56,7 +56,7 @@ if (import.meta.env.DEV) { subtitleTextColor: '#708499', textColor: '#f5f5f5', }, - initData: InitData.parse(initDataRaw), + initData: parseInitData(initDataRaw), initDataRaw, version: '7.2', platform: 'tdesktop', diff --git a/playgrounds/solid/src/mockEnv.ts b/playgrounds/solid/src/mockEnv.ts index bf07315d3..24d030454 100644 --- a/playgrounds/solid/src/mockEnv.ts +++ b/playgrounds/solid/src/mockEnv.ts @@ -1,11 +1,11 @@ -import { mockTelegramEnv, isTMA, InitData } from '@telegram-apps/sdk-solid'; +import { mockTelegramEnv, isTMA, parseInitData } from '@telegram-apps/sdk-solid'; // It is important, to mock the environment only for development purposes. When building the // application, import.meta.env.DEV will become false, and the code inside will be tree-shaken, // so you will not see it in your final bundle. if (import.meta.env.DEV) { (() => { - let shouldMock = false; + let shouldMock; const MOCK_KEY = '____mocked'; // We don't mock if we are already in a mini app. @@ -56,7 +56,7 @@ if (import.meta.env.DEV) { subtitleTextColor: '#708499', textColor: '#f5f5f5', }, - initData: InitData.parse(initDataRaw), + initData: parseInitData(initDataRaw), initDataRaw, version: '7.2', platform: 'tdesktop',