Telegram Web API Cheatsheet

Telegram Web API 备忘单

要开始使用 API，请将其放入 HTML 中：

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

当您将其添加到 HTML 中时，您将获得window.Telegram对象以及一些 CSS 样式变量。

您使用 Telegram API 的大部分工作将通过window.Telegram.WebApp进行，其中包含许多有用的方法和属性。

CSS

您可以使用 API 的 CSS 变量，以便您的 Web 应用程序将匹配用户选择的 Telegram 主题；您无需执行任何操作，CSS 变量即可使用！

 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 )

您还可以使用 JavaScript 访问它们：

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

用户认证

为了确保使用您的应用程序的用户是真实的，并且确保他们通过 Telegram 应用程序使用您的应用程序，您需要对您的用户进行身份验证；这是重要的一步，所以不要跳过它！

首先，您需要获取用户的Telegram.WebApp.initData ，它是一个包含具有以下参数的查询的字符串：

• auth_date ：打开表单时的 Unix 时间。
• hash ：所有传递参数的哈希值，机器人服务器可以使用它来检查其有效性。
• query_id ：可选。 Web 应用程序会话的唯一标识符，是通过answerWebAppQuery方法发送消息所必需的。
• user ：
  • id
  • first_name
  • last_name
  • username
  • language_code ，例如en

例子：

 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 >

其次，您需要将该查询传递到后端以验证数据。

您可以这样做：

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

使用 JavaScript，您可以像这样验证数据：

 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 ;
} ;

现在您已确保使用您的应用程序的用户是真实的，并且他们也使用 Telegram 应用程序；现在您的应用程序是安全的！

获取用户数据

从后端验证用户身份后，我们可以返回前端并获取用户数据：

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

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

// Now userData is ready to use! 

返回按钮

 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 ( ) ; 

主按钮

 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 ( ) ; 

成交确认

当您调用此方法时，它将等待，直到用户尝试关闭应用程序；然后它会要求确认

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

打开链接

在浏览器中

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

显示弹出窗口

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

有关按钮类型的更多信息请参见此处

显示警报

如果传递了可选的回调参数，则将调用回调函数，并且按下的按钮的字段 id 将作为第一个参数传递。

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

显示确认

如果传递了可选的回调参数，则当弹出窗口关闭时将调用回调函数，第一个参数将是一个布尔值，指示用户是否按下“确定”按钮。

扫描二维码

如果传递了可选的回调参数，则将调用回调函数，并且二维码中的文本将作为第一个参数传递。在此回调函数内返回 true 会导致弹出窗口关闭。

 const tg = window . Telegram . WebApp ;

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

tg . closeScanQrPopup ( ) ; 

应用程序准备好了吗？

一种通知 Telegram 应用程序 Web 应用程序已准备好显示的方法。

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

展开应用程序（全屏）

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

贡献

请随意为这份备忘单做出贡献！