Telegram Web API Cheatsheet

ورقة الغش لواجهة برمجة تطبيقات Telegram Web

لبدء استخدام واجهة برمجة التطبيقات (API)، ضع هذا في ملف HTML الخاص بك:

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

عند إضافته إلى HTML الخاص بك، ستحصل على كائن window.Telegram وأيضًا بعض متغيرات نمط CSS.

معظم عملك مع Telegram API سيكون باستخدام window.Telegram.WebApp ، الذي يحتوي على الكثير من الطرق والخصائص المفيدة.

CSS

يمكنك استخدام متغيرات CSS الخاصة بواجهة برمجة التطبيقات حتى يتطابق تطبيق الويب الخاص بك مع سمة 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 : اختياري. معرف فريد لجلسة تطبيق الويب، مطلوب لإرسال الرسائل عبر طريقة 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
}

باستخدام جافا سكريبت، يمكنك التحقق من صحة البيانات مثل هذا:

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

المزيد عن أنواع الأزرار هنا

إظهار التنبيه

إذا تم تمرير معلمة رد اتصال اختيارية، فسيتم استدعاء وظيفة رد الاتصال، وسيتم تمرير معرف الحقل الخاص بالزر المضغوط كوسيطة أولى.

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

إظهار التأكيد

إذا تم تمرير معلمة رد اتصال اختيارية، فسيتم استدعاء وظيفة رد الاتصال عند إغلاق النافذة المنبثقة، وستكون الوسيطة الأولى منطقية تشير إلى ما إذا كان المستخدم قد ضغط على الزر "موافق".

مسح رمز الاستجابة السريعة

إذا تم تمرير معلمة رد اتصال اختيارية، فسيتم استدعاء وظيفة رد الاتصال، وسيتم تمرير النص من رمز الاستجابة السريعة كوسيطة أولى. يؤدي إرجاع صحيح داخل وظيفة رد الاتصال هذه إلى إغلاق النافذة المنبثقة.

 const tg = window . Telegram . WebApp ;

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

tg . closeScanQrPopup ( ) ; 

التطبيق جاهز؟

طريقة تُعلم تطبيق Telegram بأن تطبيق الويب جاهز للعرض.

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

توسيع التطبيق (ملء الشاشة)

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

المساهمة

لا تتردد في المساهمة في ورقة الغش هذه!