DOCSEARCHbyAlgolia
Submit Docs

tma.js

repository·master·Indexed 22 days ago

https://github.com/telegram-mini-apps/tma.js

A TypeScript-first monorepo of libraries for developing Telegram Mini Apps. It includes @tma.js/bridge for low-level communication, @tma.js/sdk for client-side functionality, and framework integrations for React, Solid, Svelte, and Vue. Additionally, it provides server-side validation utilities via @tma.js/init-data-node and init-data-golang.

Tokens
92.1K
Snippets
358
Records
453
Agent score
76%

What's inside tma.js

  1. Overview of @tma.js/sdk-svelte

    master

    The @tma.js/sdk-svelte package provides Svelte.js bindings for the client SDK. It is designed to make developing Telegram Mini Apps with Svelte.js more ergonomic by providing:

    • Composables: Reactive logic for interacting with the Telegram Mini Apps platform.
    • Components: Pre-built Svelte components for common UI patterns.
    • Utilities: Helper functions specifically for Svelte developers working within the TMA environment.

  2. Overview of @tma.js/sdk-react

    master

    The @tma.js/sdk-react package provides React JS bindings for the @tma.js/sdk client SDK. It is designed to make working with the Telegram Mini Apps platform more ergonomic for React developers by providing:

    • Hooks: React hooks to access and react to Telegram Mini App state and methods.
    • Components: Pre-built components for common Telegram UI patterns.
    • Utilities: Helper functions specifically for React integration.

  3. Overview of @tma.js/sdk-vue

    master

    The @tma.js/sdk-vue package provides Vue.js bindings for the core client SDK. It is designed to bridge the gap between the Telegram Mini Apps platform and the Vue.js ecosystem by offering:

    • Composables: Reactive functions to access platform features.
    • Components: Pre-built UI components tailored for the Telegram environment.
    • Utilities: Helper functions to simplify common tasks within a Vue application.

  4. Use @tma.js/init-data-node for server-side Telegram Mini App validation

    master
    The @tma.js/init-data-node package provides utilities for handling and validating Telegram Mini App initialization data on the server side. This is essential for verifying that the data received from a client is authentic and has not been tampered with, using the data provided by the Telegram platform.

  5. Understand the Viewport concept

    master

    The Viewport is the visible portion of a Mini App. Because Mini Apps are rendered differently across various platforms, viewport data is used to ensure your application is displayed correctly.

    Key viewport properties include:

    • width and height: The dimensions of the visible area.
    • stability: A boolean indicating if the Mini App's size is stable (not expected to change imminently).
    • expansion: A boolean indicating if the Mini App has reached its maximum height.
    • fullscreen: A boolean indicating if the application is in fullscreen mode.
    • safe area: Information describing the content safe area and insets (to avoid notches, status bars, or rounded edges).

  6. Understand Telegram Mini App URL requirements

    master

    Telegram Mini Apps are web applications that require a URL to retrieve and display content. Because Telegram does not host your application, you must provide the URL yourself.

    Critical Requirements:

    • Protocol: Must use HTTPS.
    • Security: Must have a valid SSL certificate.

    Note: The Telegram test environment allows using an IP address directly, but the production environment strictly requires HTTPS.

  7. How to use the Back Button in Telegram Mini Apps

    master

    The Back Button provides a native-looking way to navigate through your application's routing history. It is important to note that the Back Button does not perform any automatic navigation; clicking it does not inherently trigger a built-in action. The developer is responsible for handling the click event to implement custom navigation logic.

    To use the Back Button, you must follow these two steps:

    1. Show the button: Call the web_app_setup_back_button method.
    2. Handle navigation: Listen for the back_button_pressed event emitted by the Telegram application when the user clicks the component.

  8. Prevent Init Data Replay Attacks

    master
    To prevent attackers from reusing stolen initialization data, you should implement an expiration check. Use the auth_date parameter provided in the init data, which represents the timestamp when the parameters were created. Compare this timestamp against your server's current time and reject the data if it is too old.

  9. How initialization data works for authentication

    master
    Initialization data can serve as a secure authentication or authorization factor. The data generated by the native Telegram application is signed using the secret key of the Telegram bot, with the signature appended to the parameters. By using the bot's secret key on your server, you can verify this signature to ensure the data was legitimately issued by Telegram for the specified user.

  10. Technical requirements for building a Mini App

    master

    Technically, a Mini App is a standard web application consisting of static files (.js, .css, and .html) displayed within a Telegram WebView.

    To build a Mini App, you can use any standard front-end technology stack. Telegram only requires the application URL, which it uses as the source for the WebView component.

    Recommended technologies:

    • Core: JavaScript, CSS, HTML
    • Advanced: TypeScript, React, SCSS, etc.

  12. Understand the concept of Features in @tma.js/sdk

    master

    In the @tma.js/sdk, a feature is a collection of related functionality grouped into a single entity. Features are not pre-initialized; developers must configure and initialize them manually to maintain full control over the lifecycle.

    Features are provided in two forms:

    1. Components: Exported as stateful objects (variables). These represent specific UI or hardware elements. Examples include backButton, mainButton, and hapticFeedback.
    2. Utilities: Exported as sets of abstract functions that are not grouped into a single variable. Examples include openLink and shareURL.