آموزش ساخت Mini App تلگرام + آموزش قدم به قدم

 

با ساخت مینی‌اپلیکیشن تلگرام، کاربران شما می‌توانند مستقیما از طریق تلگرام با اپلیکیشن‌های کوچک و کاربردی شما کار کنند. این راهنما به شما آموزش می‌دهد که چطور یک مینی‌اپلیکیشن تلگرام مانند همستر کامبت بسازید.

تلگرام با قابلیت جذاب Mini Apps، دنیایی از برنامه‌های کاربردی را به شما هدیه می‌دهد. دیگر لازم نیست برای هر کار از اپلیکیشن جداگانه استفاده کنید. Mini Appها مستقیما داخل تلگرام کار می‌کنند و با یک کلیک در دسترس شما هستند. توسعه‌دهندگان می‌توانند با استفاده از جاوا اسکریپت، Mini Appهای متنوعی بسازند که جایگزین هر وب‌سایتی شوند.

 

مزایای کلیدی مینی‌اپ تلگرام

مینی‌اپ‌های تلگرام مانند همستر کامبت، مزایای مختلفی دارند که آن‌ها را به ابزاری قدرتمند برای رشد کسب‌وکارها تبدیل می‌کند.

1. دسترسی به کاربران بیشتر: با بیش از ۸۰۰ میلیون کاربر فعال، مینی‌اپ‌ها می‌توانند به‌راحتی شما را به تعداد زیادی از افراد متصل کند. به‌ این شکل، فرصت‌های جدیدی برای تعامل با مخاطبان و رشد کسب‌ و‌ کار‌ها شکل می‌گیرد.
2. سازگار با تمام گوشی‌های هوشمند: با پشتیبانی از اندروید و آیفون، مینی‌اپ‌های تلگرام تجربه کاربری بی‌نقصی را روی تمامی دستگاه‌ها ارائه می‌دهند.
3. امکان چت با ربات‌های تلگرام داخل مینی‌اپ: از طریق مینی‌اپ‌ها، کاربران می‌توانند به‌طور مستقیم با ربات‌های تلگرام تعامل کنند و از امکانات مختلفی بهره‌مند شوند.
4. سازگار با وب ۳ (نسل جدید اینترنت): با پشتیبانی از فناوری‌های وب ۳، مینی‌اپ‌ها قابلیت‌های پیشرفته‌ای ارائه می‌دهند که می‌تواند تجربه کاربری شما را بهبود ببخشد.

 

مراحل پیاده‌سازی مینی‌اپ تلگرام

در این بخش، به‌صورت قدم‌به‌قدم به شما آموزش می‌دهیم تا بتوانید مینی‌اپ تلگرام خود را بسازید. مراحل انجام این کار، به‌صورت کلی شامل طراحی، پیاده‌سازی، راه‌اندازی و تست می‌شود.

 

(طراحی ظاهری مینی‌اپلیکیشن تلگرام) : 

تم‌های رنگی

مینی‌اپ‌های تلگرام مانند همستر کامبت، ظاهرشان را بر اساس تم رنگی که استفاده می‌کنید، تنظیم می‌کنند. این قابلیت باعث می‌شود چه از حالت روز به شب تغییر وضعیت دهید و چه از تم‌های شخصی‌سازی شده استفاده کنید، تم‌ مینی‌اپلیکیشن مطابق با تم شما باشد.

اپلیکیشن های تلگرام به خاطر سرعت، روان بودن و داشتن طراحی یکپارچه در تمامی پلتفرم ها شهرت دارند. اگر شما هم مینی‌اپ تلگرامی مانند همستر طراحی کردید، باید این ویژگی ها را داشته باشد.

اصول کلی طراحی:

• تمام المان‌ها باید واکنش‌گرا (responsive) باشند و با اولویت طراحی برای موبایل ساخته شوند.
• عناصر تعاملی باید از لحاظ سبک، رفتار و مفهوم، شبیه به اجزای رابط کاربری موجود در تلگرام باشند.
• تمامی انیمیشن ها باید روان و ترجیحا با نرخ ۶۰ فریم بر ثانیه اجرا شوند.
• برای تمام ورودی ها و تصاویر، برچسب (label) قرار دهید تا قابلیت دسترسی برای همه کاربران فراهم شود.
• مینی‌اپ تلگرام شما باید با دریافت و استفاده از رنگ های پویای مبتنی بر تم که از طریق API در اختیارتان قرار می گیرد، تجربه ای یکپارچه برای کاربر ایجاد کند.

 

روش‌های پیاده‌سازی مینی‌اپلیکیشن تلگرام :

تلگرام در حال حاضر از شش روش مختلف برای راه اندازی مینی‌اپلیکیشن‌های شبیه به همستر کامبت پشتیبانی می‌کند: از طریق دکمه کیبورد، از طریق دکمه درون خطی (Inline Button)، از طریق دکمه منو، از طریق حالت درون خطی، از طریق لینک مستقیم و از طریق منوی ضمیمه. در ادامه، هرکدام از این روش‌ها را توضیح می‌دهیم.

 

1. پیاده‌سازی مینی‌اپ با دکمه کیبورد

به طور خلاصه، اپلیکیشن های کوچکی که از طریق یک دکمه کیبورد با نوع web_app راه اندازی می‌شوند، می‌توانند با استفاده از Telegram.WebApp.sendData داده‌ها را در یک پیام سرویس به ربات ارسال کنند. این کار به ربات امکان می دهد بدون برقراری ارتباط با هیچ سرور خارجی، پاسخی را برای کاربر ارسال کند.

کاربران می توانند از طریق کیبوردهای سفارشی، دکمه های زیر پیام های ربات و همچنین با ارسال پیام های متنی آزاد یا هر یک از انواع ضمیمه های پشتیبانی شده توسط تلگرام (عکس و فیلم، فایل ها، مکان ها، مخاطبین و نظرسنجی ها) با ربات ها تعامل داشته باشند. برای انعطاف پذیری بیشتر، ربات ها می توانند از تمام قدرت HTML5 برای ایجاد رابط‌های کاربری آسان برای کاربر استفاده کنند.

شما می توانید یک دکمه KeyboardButton با نوع web_app ارسال کنید که یک اپلیکیشن کوچک را از URL مشخص شده باز کند.

برای انتقال داده ها از کاربر به ربات، اپلیکیشن کوچک می تواند متد Telegram.WebApp.sendData را فراخوانی کند. داده ها به عنوان یک رشته در یک پیام سرویس به ربات منتقل می شوند. ربات پس از دریافت آن می تواند به برقراری ارتباط با کاربر ادامه دهد.

موارد مناسب برای استفاده:

• رابط‌‌های ورودی داده سفارشی (یک تقویم شخصی سازی شده برای انتخاب تاریخ؛ انتخاب داده از لیستی با گزینه های جستجوی پیشرفته؛ یک رندوم ساز که به کاربر اجازه می‌دهد "چرخ را بچرخاند" و یکی از گزینه های موجود را انتخاب کند و ...)
• اجزای قابل استفاده مجدد که به یک ربات خاص وابسته نیستند.

 

2. پیاده‌سازی مینی‌اپ تلگرام با دکمه‌های Inline

برای مینی برنامه‌های تعاملی بیشتر مانند ربات DurgerKing، از یک دکمه درون خطی با نوع web_app استفاده کنید که اطلاعات اولیه کاربر را دریافت کرده و به نمایندگی از کاربر برای چت با ربات پیام ارسال کند. اگر به رابط کاربری پیشرفته تر و شخصی‌سازی شده نیاز دارید، می توانید با استفاده از یک دکمه درون خطی با نوع web_app یک مینی اپ باز کنید.

با کلیک روی دکمه، یک مینی‌اپلیکیشن با آدرس اینترنتی مشخص شده در دکمه باز می شود. این مینی برنامه علاوه بر تنظیمات تم کاربر، اطلاعات اولیه کاربر (شناسه، نام، نام کاربری، زبان) و یک شناسه منحصر به فرد برای جلسه (query_id) دریافت می‌کند. به این شکل، ربات اجازه می‌دهد پیام‌هایی به نمایندگی از کاربر برای ربات ارسال شود.

ربات می‌تواند با استفاده از متد answerWebAppQuery در API ربات، یک پیام درون خطی از کاربر به ربات ارسال کند و مینی برنامه را ببندد. پس از دریافت پیام، ربات می تواند به برقراری ارتباط با کاربر ادامه دهد.

موارد مناسب برای استفاده:

• سرویس های وب کامل و هر نوع یکپارچه سازی
• موارد استفاده عملاً نامحدود هستند

 

3. پیاده‌سازی Mini App تلگرام از دکمه منو

به طور پیش فرض، چت ها با ربات ها همیشه یک دکمه منوی دسترسی سریع به تمام دستورات لیست شده را فراهم می کند. با API ربات 6.0، از این دکمه می توان به جای آن برای راه اندازی یک مینی اپلیکیشن تلگرام مانند همستر کامبت استفاده کرد. برای پیکربندی دکمه منو، باید متن آن و URL مینی‌اپ را مشخص کنید. دو روش برای تنظیم این پارامترها وجود دارد:

• برای سفارشی کردن دکمه برای تمام کاربران، از @BotFather (فرمان /setmenubutton یا تنظیمات ربات > دکمه منو) استفاده کنید.
• برای سفارشی کردن دکمه برای همه کاربران و کاربران خاص، از روش setChatMenuButton در API ربات استفاده کنید. به عنوان مثال، متن دکمه را بر اساس زبان کاربر تغییر دهید یا لینک هایی به مینی برنامه های مختلف بر اساس تنظیمات کاربر در ربات خود نشان دهید.

به غیر از این، مینی برنامه های باز شده از طریق دکمه منو به همان روشی که هنگام استفاده از دکمه های درون خطی کار می کنند.

@DurgerKingBot امکان راه اندازی مینی برنامه خود را هم از یک دکمه درون خطی و هم از دکمه منو فراهم می کند.

مینی‌اپ‌های حالت درون خطی

خلاصه: مینی برنامه های راه اندازی شده از طریق دکمه InlineQueryResultsButton نوع web_app را می توان در هر جایی در حالت درون خطی استفاده کرد. کاربران می توانند در یک رابط وب محتوا ایجاد کنند و سپس به طور یکپارچه آن را از طریق حالت درون خطی به چت فعلی ارسال کنند.

می توانید از پارامتر button در روش answerInlineQuery برای نمایش یک دکمه ویژه «انتقال به مینی برنامه» در بالای نتایج درون خطی یا به جای آنها استفاده کنید. این دکمه یک مینی برنامه را از URL مشخص شده باز می کند. پس از انجام، می توانید از Telegram.WebApp.switchInlineQuery برای بازگرداندن کاربر به حالت درون خطی استفاده کنید.

مینی برنامه های درون خطی به چت دسترسی ندارند - آنها نمی توانند پیام ها را بخوانند یا پیام های جدیدی را به نمایندگی از کاربر ارسال کنند. برای ارسال پیام، کاربر باید به حالت درون خطی هدایت شود و به طور فعال یک نتیجه را انتخاب کند.

مناسب برای:

خدمات وب کامل و یکپارچه سازی در حالت درون خطی.

 

4. پیاده‌سازی مینی‌اپ تلگرام با لینک مستقیم

با استفاده از لینک‌های مستقیم، می‌توانید به طور مستقیم یک مینی‌اپ را در صفحه چت باز کنید. اگر این لینک حاوی یک پارامتر startapp با مقدار باشد، این مقدار به مینی‌اپ در فیلد start_param و پارامتر GET به نام tgWebAppStartParam ارسال می‌شود.

در این حالت، مینی‌اپ‌ها می‌توانند از پارامترهای chat_type و chat_instance برای اطلاع از وضعیت فعلی چت استفاده کنند. این ویژگی اجرای همزمان و مشترک توسط چندین عضو چت را برای ساخت تخته‌های سفید مشترک، سفارش‌های گروهی، بازی‌های چندنفره و برنامه‌های مشابه ممکن می‌کند.

مینی‌اپ‌هایی که از طریق لینک مستقیم باز می‌شوند، به محتوای چت دسترسی ندارند و نمی‌توانند به جای کاربر پیام بخوانند یا ارسال کنند. برای ارسال پیام، کاربر باید به حالت درون خطی (Inline Mode) هدایت شود و به طور فعال یک نتیجه را انتخاب کند.

 مناسب برای:

• سرویس‌های وب کامل و یکپارچه که هر کاربری می‌تواند با یک کلیک آن‌ها را باز کند.
• سرویس‌های همکاری، چندنفره یا مبتنی بر کار تیمی درون یک چت
• موارد استفاده از این قابلیت عملا نامحدود است.

 

5. پیاده‌سازی مینی‌اپ تلگرام از منوی پیوست

ربات‌های مینی اپلیکیشن می‌توانند درخواست اضافه شدن مستقیم به منوی پیوست کاربران را داشته باشند. که به آنها اجازه می‌دهد از هر نوع چتی به سرعت راه‌اندازی شوند. شما می‌توانید تنظیم کنید که اپلیکیشن مینی شما از منوی پیوست در چه نوع چت‌هایی (خصوصی، گروه‌ها، سوپرگروه‌ها یا کانال‌ها) قابل شروع باشد. ادغام با منوی پیوست در حال حاضر فقط برای تبلیغ‌کنندگان اصلی در پلتفرم تبلیغاتی تلگرام در دسترس است. با این حال، همه ربات‌ها می‌توانند از آن در محیط سرور تست استفاده کنند.

برای فعال کردن این ویژگی برای ربات، دو روش وجود دارد. از حسابی در سرور تست، @BotFather را باز کنید و دستور /setattach را ارسال کنید، یا به تنظیمات ربات بروید و منوی پیوست را تنظیم کنید. سپس URL را که برای راه‌اندازی مینی اپلیکیشن تلگرام از طریق آیکون آن در منوی پیوست باز می‌شود، مشخص کنید. شما می‌توانید با استفاده از @Botfather یک گزینه «تنظیمات» به منوی مینی‌اپ تلگرام خود اضافه کنید. وقتی کاربران این گزینه را از منو انتخاب کنند، ربات شما یک  settingsButtonClicked دریافت خواهد کرد.

علاوه بر تنظیمات تم ، ربات اطلاعات پایه‌ای کاربر (ID، نام، نام کاربری، کد زبان، عکس)، همچنین اطلاعات چت (ID، نوع، عنوان، نام کاربری، عکس) را دریافت خواهد کرد. علاوه بر این‌ها، ربات یک شناسه منحصربه‌فرد query_id دریافت می‌کند که اجازه می‌دهد پیام‌های هر نوعی از طرف کاربری که ربات را باز کرده به چت ارسال شود. ربات می‌تواند متد Bot API به نام answerWebAppQuery را فراخوانی کند. این متد، یک پیام Inline از کاربر از طریق ربات به چتی که مینی‌اپ از آن راه‌اندازی شده ارسال می‌کند و مینی اپلیکیشن را می‌بندد.

 

اجرای مینی‌اپ تلگرام

برای وصل‌کردن مینی‌اپ به تلگرام، باید اسکریپت telegram-web-app.js  را در تگ <head> قرار دهید. می‌توانید از کد زیر برای انجام این کار استفاده کنید:

HTML

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

بعد از اینکه اسکریپت وصل شد، آبجکتی با نام window.Telegram.WebApp با فیلد‌های مختلفی در دسترس قرار خواهد گرفت.

 

تست مینی‌اپ‌های تلگرام

برای تست مینی‌اپ‌های تلگرام مانند همستر کامبت، باید به محیط تست وارد شوید. برای ورود به محیط تست، از یکی از روش‌های زیر استفاده کنید:

-IOS: ده بار روی آیکون تنظیمات ضربه بزنید > حساب‌ها > ورود به حساب دیگر > تست.
- Telegram Desktop: باز کردن ☰ تنظیمات > Shift + Alt + کلیک راست ‘Add Account’ و انتخاب ‘Test Server’.
- macOS: روی آیکون تنظیمات 10 بار کلیک کنید تا منوی Debug باز شود، ⌘ + کلیک ‘Add Account’ و ورود با شماره تلفن.

محیط تست کاملاً جدا از محیط اصلی است، بنابراین نیاز به ایجاد یک حساب کاربری جدید و یک ربات جدید با استفاده از @BotFather دارید. پس از دریافت توکن ربات، می‌توانید درخواست‌ها را به Bot API به این صورت ارسال کنید: https://api.telegram.org/bot<token>/test/METHOD_NAME

توجه: هنگام کار با محیط تست، می‌توانید از لینک‌های HTTP بدون TLS برای تست مینی اپلیکیشن خود استفاده کنید.

 

حالت دیباگ برای مینی‌اپلیکیشن‌های تلگرام

برای یافتن باگ‌های مینی‌اپ در پلتفرم‌های مختلف، باید از ابزار‌های متفاوتی استفاده کنید:

• اندروید

1. فعال کردن USB-Debugging روی دستگاه خود.
2. در تنظیمات تلگرام، به پایین اسکرول کنید، دوبار روی نسخه تلگرام ضربه بزنید.
3. در تنظیمات اشکال‌زدایی، "Enable WebView Debug" را انتخاب کنید.
4. تلفن خود را به کامپیوتر وصل کنید و chrome://inspect/#devices را در مرورگر کروم باز کنید – مینی اپلیکیشن خود را در آنجا خواهید دید وقتی که آن را روی تلفن خود اجرا می‌کنید.

•  تلگرام دسکتاپ در ویندوز و لینوکس

1. نسخه بتای Telegram Desktop را برای ویندوز یا لینوکس دانلود و اجرا کنید (هنوز برای Telegram Desktop در macOS پشتیبانی نمی‌شود).
2. به تنظیمات بروید > تنظیمات پیشرفته > تنظیمات تجربی > "Enable webview inspection" را فعال کنید.
3. در WebView راست کلیک کنید و "Inspect" را انتخاب کنید.

•  تلگرام macOS

1. نسخه بتای Telegram macOS را دانلود و اجرا کنید.
2. 5 بار سریع روی آیکون تنظیمات کلیک کنید تا منوی debug باز شود و “Debug Mini Apps” را فعال کنید.
3. در مینی اپلیکیشن راست کلیک کنید و "Inspect Element" را انتخاب کنید.

با انجام این دستورالعمل‌ها قبل از راه‌اندازی مینی‌اپ در محیط اصلی، می‌توانید اطمینان حاصل کنید که مینی‌اپ شما عملکرد صحیحی دارد.

 

جمع‌بندی

کلیدی‌ترین مراحل در ساخت مینی‌اپ تلگرام، طراحی‌ ظاهری، پیاده‌سازی، اجرا و تست و دیباگ هستند. با انجام دقیق تمام مراحل گفته‌شده، می‌توانید مینی‌اپلیکیشن تلگرامی شبیه به همستر کامبت بسازید.

 

سوالات متداول

1. آیا می‌توانم مینی‌اپ تلگرام خود را در همه چت‌ها راه‌اندازی کنم؟

بله، می‌توانید تنظیم کنید که مینی‌اپلیکیشن شما در چت‌های خصوصی، گروه‌ها، سوپرگروه‌ها یا کانال‌ها قابل راه‌اندازی باشد.

2. آیا روشی برای درآمد‌زایی از مینی‌اپ تلگرام وجود دارد؟

راه‌های مختلفی برای در‌آمد‌زایی از مینی‌اپ وجود دارند. بطور مثال می‌توانید محتوای‌آموزشی تولید کنید و از قابلیت پرداخت درون برنامه‌ای تلگرام برای دریافت هزینه از کاربران، به‌منظور استفاده از محتوا‌ی ویژه مینی‌اپ خود استفاده کنید.