twa-client-sdk v2.1.2

SDK

Dead-simple, tree-shakeable, side-effects free, made from scratch TypeScript library for communication with Telegram Web Apps functionality.

Code of this library was written with aim to make developers communication with Telegram way easier. It contains a lot of separate components which are responsible for their own part of Telegram Web Apps ecosystem.

Before starting to use SDK, we highly recommend learning Web Apps documentation to understand platform concepts.

⚠️ This library is independent. Please, do not associate this SDK with library created by Telegram or TON Foundation developers and their documentation.

Table of contents

• Motivation
• Installation
• Usage
• Components

Motivation

• Official implementation supports usage only through global window object that is not modern and not that comfortable as importing functionality with ES6 imports. Nevertheless, it does not mean, this use case should not exist. Some applications may not support modern way of using packages and as a result, the only one possible solution for them is usage through window object;
• Official implementation language is JavaScript without usage of JSDoc. It is rather important to use TypeScript to let developers know which types they use. Additionally, TS code is way more supportable;
• Official implementation contains almost no comments. So, most of the time, it is hard to understand current code flow;
• Original library contains bugs and potential weak spots.

Installation

npm i twa-client-sdk

or

yarn add twa-client-sdk

Usage

Preparing visual part

It is not secret, that visual part of application is rather important for user. It means, that your application should not have any visual problems. We can say the same about application "flashes", when its color scheme changes on flight. To prevent application from flashing, it is required to know theme colors at the moment, when DOM body starts rendering.

This package itself has no utility which provides such kind of behavior. The reason is, ecosystem contains separate component responsible for this functionality. To learn how it works, visit this section of documentation.

Initialization

According to logic, this package provides full control over its lifecycle, its initialization is on your shoulders. It means, that there are no already initialized global components which could be used by developer, he has to create them.

To make developers life easier, package contains special function called init, which allows to get everything package needs and work with created components:

import {init} from 'twa-client-sdk';

init().then(components => {
    // Now we have all initialized components.
});

After this step, it is allowed to start using Web Apps functionality and trust components properties.

import {init} from 'twa-client-sdk';

init().then(components => {
    const {mainButton, viewport} = components;

    // Add main button event click which will lead to
    // application expansion.
    mainButton.on('click', viewport.expand);

    // Update main button information and show it.
    mainButton
        .setColor('#ff0000')
        .setTextColor('#ffffff')
        .setText('Expand')
        .enable()
        .show();
});

Debug mode

To display additional debug messages, use the first argument in init function:

import {init} from 'twa-client-sdk';

// Init debug mode.
init(true);

Components

Each component contains its own documentation:

• BackButton
• Bridge
• HapticFeedback
• InitData
• MainButton
• Popup
• ThemeParams
• Viewport
• WebApp

Contribution

Any contribution is appreciated. Feel free to create new feature requests, bug reports etc.

In case, you found a bug in Web Apps platform (not this SDK), please, create new issue here.