Telegram Web API Cheatsheet

Lembar Cheat API Web Telegram

Untuk mulai menggunakan API, masukkan ini ke dalam HTML Anda:

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

Saat Anda menambahkannya ke HTML, Anda mendapatkan objek window.Telegram dan juga beberapa variabel gaya CSS.

Sebagian besar pekerjaan Anda dengan API Telegram akan dilakukan dengan window.Telegram.WebApp , yang berisi banyak metode dan properti berguna.

CSS

Anda dapat menggunakan variabel CSS API sehingga aplikasi web Anda akan cocok dengan tema Telegram pengguna yang mereka pilih; Anda tidak perlu melakukan apa pun, variabel CSS siap digunakan!

 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 )

Anda juga dapat mengaksesnya menggunakan JavaScript:

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

Otentikasi Pengguna

Untuk memastikan bahwa pengguna yang menggunakan aplikasi Anda adalah pengguna asli dan juga untuk memastikan mereka menggunakan aplikasi Anda dari aplikasi Telegram, Anda perlu mengautentikasi pengguna Anda; ini adalah langkah penting, jadi jangan lewatkan!

Pertama, Anda perlu mendapatkan Telegram.WebApp.initData pengguna, yang merupakan string yang berisi kueri dengan parameter berikut:

• auth_date : Waktu Unix ketika formulir dibuka.
• hash : Hash dari semua parameter yang diteruskan, yang dapat digunakan server bot untuk memeriksa validitasnya.
• query_id : Opsional. Pengidentifikasi unik untuk sesi Aplikasi Web, diperlukan untuk mengirim pesan melalui metode answerWebAppQuery .
• user :
  • id
  • first_name
  • last_name
  • username
  • language_code , misalnya en

Contoh:

 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 >

Kedua, Anda harus meneruskan kueri tersebut ke backend untuk memvalidasi data.

Inilah cara Anda melakukannya:

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

Dengan menggunakan JavaScript, Anda dapat memvalidasi data seperti itu:

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

Sekarang Anda memastikan bahwa pengguna yang menggunakan aplikasi Anda adalah pengguna asli dan mereka juga menggunakan aplikasi Telegram; sekarang aplikasi Anda aman!

Mendapatkan Data Pengguna

Setelah mengautentikasi pengguna dari backend, kita dapat kembali ke frontend dan mengambil data pengguna:

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

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

// Now userData is ready to use! 

Tombol Kembali

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

Tombol Utama

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

Konfirmasi Penutupan

Saat Anda memanggil metode ini, metode ini akan menunggu hingga pengguna mencoba menutup aplikasi; maka ia akan meminta konfirmasi

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

Buka Tautan

Di peramban

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

Tampilkan Popup

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

Lebih lanjut tentang jenis tombol di sini

Tampilkan Peringatan

Jika parameter panggilan balik opsional diteruskan, fungsi panggilan balik akan dipanggil, dan id bidang dari tombol yang ditekan akan diteruskan sebagai argumen pertama.

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

Tampilkan Konfirmasi

Jika parameter panggilan balik opsional diteruskan, fungsi panggilan balik akan dipanggil ketika popup ditutup, dan argumen pertama akan berupa boolean yang menunjukkan apakah pengguna menekan tombol 'OK'.

Memindai Kode QR

Jika parameter panggilan balik opsional diteruskan, fungsi panggilan balik akan dipanggil, dan teks dari kode QR akan diteruskan sebagai argumen pertama. Mengembalikan nilai true di dalam fungsi panggilan balik ini menyebabkan popup ditutup.

 const tg = window . Telegram . WebApp ;

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

tg . closeScanQrPopup ( ) ; 

Aplikasi Siap?

Sebuah metode yang menginformasikan aplikasi Telegram bahwa Aplikasi Web siap ditampilkan.

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

Perluas Aplikasi (Layar Penuh)

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

Berkontribusi

Jangan ragu untuk berkontribusi pada lembar contekan ini!