کتاب راهنمای ایجاد برنامه های تلگرام مینی

این کتابچه راهنمای ایجاد برنامه های مینی تلگرام را تشریح می کند. این بر دقت تأکید می کند ، توضیحات مفصلی را ارائه می دهد ، و شامل برچسب زدن اختیاری/مورد نیاز برای وضوح است.

1. درک برنامه های مینی تلگرام

• تعریف: برنامه های Telegram Mini برنامه های وب هستند که مستقیماً در برنامه Telegram اجرا می شوند. آنها بدون نیاز به کاربران برای ترک محیط تلگرام ، تجربه کاربری یکپارچه را ارائه می دهند.
• ویژگی های کلیدی:
  • ادغام بومی: ادغام عمیق با ویژگی های تلگرام مانند پرداخت ، مخاطبین و مکان.
  • کراس پلتفرم: در تمام سیستم عامل های تلگرام (iOS ، Android ، Desktop) کار می کند.
  • ایمن: از زیرساخت های امن تلگرام استفاده می کند.
  • قابل کشف: می توان از چت ها ، رباتها یا مستقیماً راه اندازی شد.

2. پیش نیازها

• ابزار: یک محیط توسعه وب (به عنوان مثال ، در مقابل کد ، متن عالی).
• مهارت ها:
  • HTML ، CSS ، JavaScript/TypeScript: برای ایجاد رابط کاربری و منطق ضروری است.
  • توسعه باطن (اختیاری): اگر مینی برنامه شما به منطق سمت سرور نیاز دارد ، به یک زبان باطن نیاز دارید (به عنوان مثال ، node.js ، پایتون ، برو).
• ربات تلگرام: یک ربات تلگرام برای میزبانی و راه اندازی برنامه مینی خود لازم است. می توانید یکی را با استفاده از Botfather ایجاد کنید (به کتابچه قبلی مراجعه کنید).

3. تنظیم محیط توسعه خود

1. یک چارچوب را انتخاب کنید (توصیه می شود): در حالی که می توانید یک برنامه کوچک با جاوا اسکریپت وانیلی بسازید ، با استفاده از چارچوبی مانند React ، Vue یا Svelte می تواند به طور قابل توجهی کارایی و قابلیت حفظ توسعه را بهبود بخشد. React به دلیل معماری مبتنی بر مؤلفه و اکوسیستم بزرگ ، یک انتخاب محکم است.

2. ایجاد یک پروژه جدید (مثال React):

   npx create-react-app my-telegram-miniapp --template typescript
   cd my-telegram-miniapp
   

3. برنامه وب تلگرام SDK را نصب کنید: این SDK دسترسی به API مینی برنامه Telegram را فراهم می کند.

   npm install @twa-dev/sdk
   

4. نصب کردن telegram-web-app انواع:

   npm install --save-dev @types/telegram-web-app
   

4. اولیه سازی برنامه وب تلگرام SDK

• اهمیت: قبل از استفاده از هر یک از ویژگی های آن ، SDK باید اولیه شود.

1. SDK را در مؤلفه اصلی خود آغاز کنید (به عنوان مثال ، src/App.tsx):

import React, { useEffect } from 'react';
import './App.css';
import { useTelegram } from './hooks/useTelegram';

function App() {
  const { tg, onToggleButton } = useTelegram();

  useEffect(() => {
    tg.ready();
  }, [tg]);

  return (
    <div className="App">
      Content
    </div>
  );
}

export default App;

// src/hooks/useTelegram.ts
import { useEffect, useState } from 'react';

const tg = window.Telegram.WebApp;

export function useTelegram() {

    const onClose = () => {
        tg.close()
    }

    const onToggleButton = () => {
        if(tg.MainButton.isVisible) {
            tg.MainButton.hide();
        } else {
            tg.MainButton.show();
        }
    }

    return {
        tg,
        onClose,
        onToggleButton,
        user: tg.initDataUnsafe?.user,
        queryId: tg.initDataUnsafe?.query_id,
    }
}

1. توضیح:

*   **`window.Telegram.WebApp`:** This global object is provided by Telegram when the Mini App is running within the Telegram environment.
*   **`tg.ready()`:**  This function signals to Telegram that your Mini App is ready to be displayed.  It's crucial to call this early in your app's lifecycle.
*   **`useEffect`:**  The `useEffect` hook ensures that `tg.ready()` is called only once after the component mounts.

5. اجرای ویژگی های اساسی

• هدف: عملکردهای اصلی برنامه را نشان دهید.

1. تنظیم رنگ پس زمینه:

useEffect(() => {
    tg.setBackgroundColor("#f0f0f0");
}, [tg]);

1. نمایش و پنهان کردن دکمه اصلی:

useEffect(() => {
    tg.MainButton.setText('Close')
    tg.MainButton.onClick(onClose)
}, [tg])

1. دسترسی به داده های کاربر:

const { user } = useTelegram();

// ...

{user?.id}

1. توضیح:

*   **`tg.setBackgroundColor()`:** Sets the background color of the Mini App.
*   **`tg.MainButton`:**  Provides access to the main button at the bottom of the Mini App.  You can customize its text, color, and click handler.
*   **`tg.initDataUnsafe.user`:** Contains information about the current user (ID, first name, last name, username).  **Important:** This data is *unsafe* because it's not cryptographically verified.  For sensitive operations, you should verify the data using the `initData` property (see Security Considerations).

6. رسیدگی به رویدادها

• اهمیت: برنامه های مینی می توانند به رویدادهای مختلفی که توسط کاربر یا تلگرام ایجاد می شود پاسخ دهند.

1. گوش دادن به themeChanged رویداد:

useEffect(() => {
    tg.onEvent('themeChanged', function(){
        document.body.style.backgroundColor = tg.themeParams.bg_color;
    })
}, [tg])

1. توضیح:

*   **`tg.onEvent()`:**  Registers a callback function to be executed when a specific event occurs.
*   **`themeChanged`:**  This event is triggered when the user changes the Telegram theme (e.g., from light to dark mode).
*   **`tg.themeParams`:**  Provides access to the current theme parameters (e.g., background color, text color).

7. ارسال داده ها به ربات

• مکانیسم: برنامه های مینی می توانند داده ها را به ربات هایی که آنها را راه اندازی کرده است ، ارسال کنند.

1. ارسال داده با استفاده از tg.sendData():

const sendDataToBot = () => {
    tg.sendData(JSON.stringify({ message: 'Hello from the Mini App!' }));
};

1. رسیدگی به داده ها در ربات (Node.js مثال):

bot.on('message', (msg) => {
  if (msg.web_app_data) {
    const data = JSON.parse(msg.web_app_data.data);
    console.log('Received data from Mini App:', data);
    bot.sendMessage(msg.chat.id, `You sent: ${data.message}`);
  }
});

1. توضیح:

*   **`tg.sendData()`:** Sends a string of data back to the bot.  It's common to serialize the data as JSON.
*   **`msg.web_app_data`:**  In your bot's message handler, check for the `web_app_data` property.  This contains the data sent from the Mini App.
*   **`msg.web_app_data.data`:**  The actual data string sent by the Mini App.

8. ملاحظات امنیتی

• تأیید داده ها: همیشه تأیید کنید initData استفاده از نشانه ربات برای اطمینان از دستکاری داده ها.
• ضد عفونی ورودی: برای جلوگیری از حملات اسکریپت در سایت (XSS) ، ورودی کاربر را ضد عفونی کنید.
• https: برنامه مینی شما باید از طریق https سرو شود.

1. تأیید initData (مثال ساده – node.js):

import crypto from 'crypto';

function verifyTelegramWebAppInitData(initData: string, botToken: string): boolean {
  const secretKey = crypto
    .createHmac('sha256', 'WebAppData')
    .update(botToken)
    .digest();

  const dataCheckString = new URLSearchParams(initData).sort().toString();
  const hmac = crypto
    .createHmac('sha256', secretKey)
    .update(dataCheckString)
    .digest('hex');

  const expectedHash = new URLSearchParams(initData).get('hash');

  return hmac === expectedHash;
}

9. راه اندازی برنامه مینی خود

1. یک دستور ربات ایجاد کنید: از Botfather برای ایجاد یک دستور که برنامه مینی شما را راه اندازی می کند استفاده کنید (به عنوان مثال ، /webapp).

2. دستور را در ربات خود پیاده سازی کنید:

bot.onText(/\/webapp/, (msg) => {
  const chatId = msg.chat.id;
  bot.sendWebApp(chatId, {
    url: 'YOUR_MINI_APP_URL',
  });
});

1. توضیح:

*   bot.sendWebApp():  Sends a message with a button that launches the Mini App.


  url:  The URL of your deployed Mini App.

1. آزمایش و اشکال زدایی

• دسک تاپ تلگرام: برای اشکال زدایی آسان تر از دسک تاپ تلگرام استفاده کنید. ابزارهای توسعه دهنده (معمولاً با فشار دادن F12) را باز کنید تا درخواست های کنسول و شبکه مینی برنامه را بازرسی کنید.
• اشکال زدایی از راه دور (Android): از ویژگی اشکال زدایی از راه دور Chrome برای اشکال زدایی برنامه Mini خود در حال اجرا بر روی یک دستگاه Android استفاده کنید.

11. استقرار

• سیستم عامل ها: برنامه مینی خود را به هر بستر میزبانی وب که از HTTPS پشتیبانی می کند ، مستقر کنید (به عنوان مثال ، NetLify ، Vercel ، AWS S3 ، Google Cloud Storage).
• ادغام مداوم/استقرار مداوم (CI/CD): فرآیند استقرار را خودکار کنید.

12. ویژگی ها و ملاحظات پیشرفته

• پرداخت ها: پرداخت های تلگرام را در برنامه مینی خود ادغام کنید.
• مکان: به مکان کاربر (با اجازه آنها) دسترسی پیدا کنید.
• بازخورد هاپتیک: برای ارتقاء تجربه کاربر ، بازخورد Haptic ارائه دهید.
• سفارشی سازی موضوع: برنامه مینی خود را با موضوع تلگرام کاربر تطبیق دهید.
• ذخیره داده ها: استفاده کردن localStorage یا sessionStorage برای ذخیره اطلاعات سمت مشتری.

منابع

این کتاب راهنما یک راهنمای جامع برای ایجاد برنامه های مینی تلگرام ارائه می دهد. به یاد داشته باشید که برای به روزترین اطلاعات و ویژگی های پیشرفته با مستندات رسمی تلگرام مشورت کنید. موفق باشید!