Telegram Web API Cheatsheet

Cheatsheet für die Telegram-Web-API

Um die API zu verwenden, fügen Sie Folgendes in Ihren HTML-Code ein:

 < script src =" https://telegram.org/js/telegram-web-app.js " > </ script >

Wenn Sie es zu Ihrem HTML hinzufügen, erhalten Sie das window.Telegram -Objekt und auch einige CSS-Stilvariablen.

Der Großteil Ihrer Arbeit mit der Telegram-API wird mit window.Telegram.WebApp erfolgen, das viele nützliche Methoden und Eigenschaften enthält.

CSS

Sie können die CSS-Variablen der API verwenden, damit Ihre Web-App dem vom Benutzer ausgewählten Telegram-Thema entspricht. Sie müssen nichts tun, die CSS-Variablen sind sofort einsatzbereit!

 var ( --tg-theme-bg-color )
var ( --tg-theme-text-color )
var ( --tg-theme-hint-color )
var ( --tg-theme-link-color )
var ( --tg-theme-button-color )
var ( --tg-theme-button-text-color )
var ( --tg-theme-secondary-bg-color )

Sie können auch mit JavaScript darauf zugreifen:

 const {
  bg_color ,
  text_color ,
  hint_color ,
  button_color ,
  button_text_color ,
  secondary_bg_color ,
} = Telegram . WebApp . themeParams ; 

Benutzerauthentifizierung

Um sicherzustellen, dass es sich bei den Benutzern, die Ihre App verwenden, um echte Benutzer handelt, und um sicherzustellen, dass sie Ihre App über die Telegram-App verwenden, müssen Sie Ihre Benutzer authentifizieren. Dies ist ein wichtiger Schritt, also überspringen Sie ihn nicht!

Zuerst müssen Sie die Telegram.WebApp.initData des Benutzers abrufen, eine Zeichenfolge, die eine Abfrage mit diesen Parametern enthält:

• auth_date : Unix-Zeit, zu der das Formular geöffnet wurde.
• hash : Ein Hash aller übergebenen Parameter, anhand dessen der Bot-Server deren Gültigkeit überprüfen kann.
• query_id : Optional. Eine eindeutige Kennung für die Web-App-Sitzung, die zum Senden von Nachrichten über die Methode answerWebAppQuery erforderlich ist.
• user :
  • id
  • first_name
  • last_name
  • username
  • language_code , zum Beispiel en

Beispiel:

 query_id = < query_id > &user=%7B%22id%22%3A < user_id > %2C%22first_name%22%3A%22 < first_name > %22%2C%22last_name%22%3A%22 < last_name > %22%2C%22username%22%3A%22 < username > %22%2C%22language_code%22%3A%22 < language_code > %22%7D&auth_date= < auth_date > &hash= < hash >

Zweitens müssen Sie diese Abfrage an das Backend übergeben, um die Daten zu validieren.

So machen Sie es:

 data_check_string = ...
secret_key = HMAC_SHA256 ( < bot_token > , "WebAppData")
if (hex(HMAC_SHA256(data_check_string, secret_key)) == hash) {
  // Data is from Telegram
}

Mithilfe von JavaScript können Sie die Daten folgendermaßen validieren:

 const verifyTelegramWebAppData = ( telegramInitData : string ) => {
  // The data is a query string, which is composed of a series of field-value pairs.
  const encoded = decodeURIComponent ( telegramInitData ) ;

  // HMAC-SHA-256 signature of the bot's token with the constant string WebAppData used as a key.
  const secret = crypto . createHmac ( "sha256" , "WebAppData" ) . update ( botToken ) ;

  // Data-check-string is a chain of all received fields'.
  const arr = encoded . split ( "&" ) ;
  const hashIndex = arr . findIndex ( ( str ) => str . startsWith ( "hash=" ) ) ;
  const hash = arr . splice ( hashIndex ) [ 0 ] . split ( "=" ) [ 1 ] ;
  // Sorted alphabetically
  arr . sort ( ( a , b ) => a . localeCompare ( b ) ) ;
  // In the format key=<value> with a line feed character ('n', 0x0A) used as separator
  // e.g., 'auth_date=<auth_date>nquery_id=<query_id>nuser=<user>
  const dataCheckString = arr . join ( "n" ) ;

  // The hexadecimal representation of the HMAC-SHA-256 signature of the data-check-string with the secret key
  const _hash = crypto
    . createHmac ( "sha256" , secret . digest ( ) )
    . update ( dataCheckString )
    . digest ( "hex" ) ;

  // If hash is equal, the data may be used on your server.
  // Complex data types are represented as JSON-serialized objects.
  return _hash === hash ;
} ;

Jetzt haben Sie sichergestellt, dass der Benutzer, der Ihre App verwendet, der echte ist und dass er auch die Telegram-App verwendet. Jetzt ist Ihre App sicher!

Benutzerdaten abrufen

Nachdem wir den Benutzer im Backend authentifiziert haben, können wir zum Frontend zurückkehren und die Daten des Benutzers abrufen:

 const params = new URLSearchParams ( Telegram . WebApp . initData ) ;

const userData = Object . fromEntries ( params ) ;
userData . user = JSON . parse ( userData . user ) ;

// Now userData is ready to use! 

Zurück-Taste

 const tg = Telegram . WebApp ;

// Show the back button
tg . BackButton . show ( ) ;

// Check if the button is visible
tg . BackButton . isVisible ;

// Click Event
const goBack = ( ) => {
  // Callback code
} ;

tg . BackButton . onClick ( goBack ) ;

// Remove Click Event
tg . BackButton . offClick ( goBack ) ;

// Hide the back button
tg . BackButton . hide ( ) ; 

Haupttaste

 const tg = Telegram . WebApp . MainButton ;

// Properties
tg . text ; // You can change the value
tg . color ; // You can change the value
tg . textColor ; // You can change the value
tg . isVisible ;
tg . isActive ;
tg . isProgressVisible ;

// Events
tg . onClick ( callback ) ;
tg . offClick ( callback ) ;

// Methods
tg . setText ( "buy" ) ;
tg . show ( ) ;
tg . hide ( ) ;
tg . enable ( ) ; // Default
tg . disable ( ) ; // If the button is disabled, then it will not work when clicked
tg . showProgress ( true ) ; // Shows a spinning icon; if you passed into it `false`, then it will disable the button when loading
tg . hideProgress ( ) ; 

Abschlussbestätigung

Wenn Sie diese Methode aufrufen, wartet sie, bis der Benutzer versucht, die App zu schließen. dann wird nach einer Bestätigung gefragt

 const tg = Telegram . WebApp ;
tg . enableClosingConfirmation ( ) ;
tg . disableClosingConfirmation ( ) ; 

Öffnen Sie einen Link

In einem Browser

 const tg = window . Telegram . WebApp ;
tg . openLink ( "https://youtube.com" ) ; 

Popup anzeigen

 const tg = Telegram . WebApp ;
tg . showPopup (
  {
    title : "Sample Title" , // Optional
    message : "Sample message" ,
    buttons : [ { type : "destructive" , text : "oh hell nah" } ] , // Optional
  } ,
  callback
) ;

Weitere Informationen zu Schaltflächentypen finden Sie hier

Warnung anzeigen

Wenn ein optionaler Callback-Parameter übergeben wurde, wird die Callback-Funktion aufgerufen und die Feld-ID des gedrückten Buttons als erstes Argument übergeben.

 const tg = window . Telegram . WebApp ;
tg . showAlert ( "sample alert" , callback ) ;

Bestätigen anzeigen

Wenn ein optionaler Rückrufparameter übergeben wurde, wird die Rückruffunktion aufgerufen, wenn das Popup geschlossen wird, und das erste Argument ist ein boolescher Wert, der angibt, ob der Benutzer die Schaltfläche „OK“ gedrückt hat.

QR-Code scannen

Wenn ein optionaler Callback-Parameter übergeben wurde, wird die Callback-Funktion aufgerufen und der Text aus dem QR-Code als erstes Argument übergeben. Die Rückgabe von „true“ innerhalb dieser Rückruffunktion führt dazu, dass das Popup geschlossen wird.

 const tg = window . Telegram . WebApp ;

tg . showScanQrPopup ( { text : "capture" } , callback ) ;

tg . closeScanQrPopup ( ) ; 

Bereit für die App?

Eine Methode, die die Telegram-App darüber informiert, dass die Web-App zur Anzeige bereit ist.

 const tg = window . Telegram . WebApp ;
tg . ready ( ) ; 

App erweitern (Vollbild)

 const tg = window . Telegram . WebApp ;
tg . isExpanded ;
tg . expand ( ) ; 

Mitwirken

Fühlen Sie sich frei, zu diesem Cheatsheet beizutragen!