کیت توسعه برنامه در پیام رسان ایتا
کیت توسعه SDK رابطی است بین برنامه (یا برنامک) و محیط پیام‌رسان ایتا که اجازه می‌دهد برنامک با امکانات ایتا (مثل بستن، تمام‌صفحه شدن و غیره) تعامل داشته باشد.
توابع این کیت به صورت callBack عمل می‌کنند و فقط در محیط ایتا فعال هستند (نه مرورگرهای معمولی).
اتصال به کیت توسعه
برای اتصال برنامک به کیت توسعه، اسکریپت eitaa-web-app.js را در
تگ <head> و پیش از هر اسکریپت دیگری، با استفاده از کد زیر اضافه کنید:
js
<script src="https://developer.eitaa.com/eitaa-web-app.js"></script>
هشدار:
لطفاً از دانلود و ذخیره‌سازی فایل eitaa-web-app.js به‌صورت محلی در پروژه خودداری کنید. این فایل باید مستقیماً از
آدرس رسمی بارگذاری شود
دلایل:
- دریافت به‌روزرسانی‌ها: نسخه‌های جدید این فایل ممکن است شامل بهبود عملکرد، سازگاری با نسخه‌های جدید کلاینت، و قابلیت‌های تازه باشند که در صورت استفاده محلی دریافت نمی‌کنید.
- به‌روزرسانی‌های امنیتی: اصلاحات امنیتی به‌صورت مداوم در نسخه رسمی اعمال می‌شوند. نسخه‌های محلی در برابر آسیب‌پذیری‌های احتمالی محافظت‌شده نیستند.
- ناهمخوانی با کلاینت: نسخه محلی ممکن است با نسخه فعلی کلاینت ایتا هماهنگ نباشد و منجر به رفتار ناپایدار یا نادرست در برنامک شود.
- پشتیبانی فنی محدود: در صورت بروز خطا هنگام استفاده از نسخه محلی، تیم پشتیبانی ممکن است قادر به راهنمایی یا رفع مشکل نباشد.
پس از اتصال اسکریپت یک شیء با نام window.Eitaa.WebApp با مقادیر زیر در دسترس قرار می‌گیرد:
| مقدار | نوع | توضیحات | نسخه کیت |
|---|---|---|---|
| initData | String | یک رشته از داده خام انتقال داده شده به برنامک که مناسب اعتبار سنجی داده است. توجه: اعتبارسنجی داده حتما در سرور انجام شود! | |
| initDataUnsafe | WebAppInitData | یک شیء با داده‌های ورودی به برنامک منتقل شده است. توجه: به داده‌های این فیلد نباید اعتماد کرد. شما فقط باید از داده‌های initData در سمت سرور و آن هم فقط پس از تأیید اعتبار استفاده کنید. | |
| version | String | نسخه کیت توسعه موجود در برنامه ایتای کاربر. | |
| platform | String | پلتفرم ایتای کاربر. | |
| colorScheme | String | طرح رنگی که در حال حاضر در برنامه ایتا استفاده میشود. یا "light" یا "dark". همچنین در CSS به عنوان متغیر var(--tg-color-scheme) موجود است. | |
| themeParams | ThemeParams | یک شیء حاوی تنظیمات قالب(تم) فعلی مورد استفاده در برنامه ایتا. | |
| isExpanded | Boolean | اگر True باشد, برنامک به حداکثر ارتفاع موجود گسترش یافته است و اگر False باشد، برنامک فقط بخشی از صفحه را اشغال کند. با استفاده از متد ()expand می‌توان آن را تا تمام ارتفاع گسترش داد. | |
| isActive | Boolean | نشان می‌دهد که برنامک در حال حاضر فعال (در فوکوس) است یا خیر. | |
| isFullscreen | Boolean | نشان می‌دهد که برنامک در حالت تمام‌صفحه قرار دارد یا خیر. | |
| isOrientationLocked | Boolean | نشان می‌دهد که قفل چرخش صفحه فعال است یا خیر. |  |
| bottomBarColor | String | رنگ فعلی نوار پایین برنامک. | |
| SecondaryButton | BottomButton | شیء کنترل دکمه ثانویه که در پایین برنامک نمایش داده میشود. | |
| safeAreaInset | SafeAreaInset | شیء مربوط به فاصله‌های امن صفحه برای جلوگیری از هم‌پوشانی با عناصر سیستمی. | |
| contentSafeAreaInset | ContentSafeAreaInset | شیء مربوط به فاصله‌های امن ناحیه محتوای صفحه برای جلوگیری از هم‌پوشانی با عناصر رابط کاربری. | |
| viewportHeight | Float | ارتفاع فعلی ناحیه قابل مشاهده برنامک. همچنین در CSS به عنوان متغیر var(--tg-viewport-height) موجود است. این برنامه می‌تواند فقط قسمت بالای برنامک را نمایش دهد و قسمت پایین آن در خارج از صفحه نمایش باقی بماند. از این موقعیت، کاربر می‌تواند برنامک را به حداکثر ارتفاع خود بکشد، در حالی که برنامک می‌تواند با فراخوانی متد ()expand همین کار را انجام دهد. با تغییر موقعیت برنامک، مقدار ارتفاع فعلی ناحیه قابل مشاهده به صورت بلادرنگ به‌روز میشود. لطفاً توجه داشته باشید که نرخ تازه‌سازی این مقدار برای دنبال کردن هموار حاشیه پایین پنجره کافی نیست و نباید از آن برای پین کردن عناصر رابط به پایین ناحیه قابل مشاهده استفاده شود. برای این منظور، بهتر است از مقدار فیلد viewportStableHeight استفاده کنید. | |
| viewportStableHeight | Float | ارتفاع ناحیه قابل مشاهده برنامک در آخرین وضعیت پایدار آن. همچنین در CSS به عنوان متغیر var(--tg-viewport-stable-height) موجود است. این برنامه می‌تواند فقط قسمت بالای برنامک را نمایش دهد و قسمت پایین آن در خارج از صفحه نمایش باقی بماند. از این موقعیت، کاربر می‌تواند برنامک را به حداکثر ارتفاع خود بکشد، در حالی که برنامه می‌تواند با فراخوانی متد ()expand همین کار را انجام دهد. برخلاف مقدار viewportHeight، مقدار viewportStableHeight با تغییر موقعیت برنامک با حرکات کاربر یا در طول انیمیشن‌ها تغییر نمی‌کند. مقدار viewportStableHeight پس از تکمیل تمام حرکات و انیمیشن‌ها و رسیدن برنامک به اندازه نهایی خود به‌روز میشود. به رویداد viewportChanged با پارامتر ورودی isStateStable=true توجه کنید که به شما امکان می‌دهد زمان تغییر وضعیت پایدار ارتفاع ناحیه قابل مشاهده را ردیابی کنید. | |
| headerColor | String | رنگ هِدر فعلی در قالب RRGGBB#. | |
| backgroundColor | String | رنگ پس زمینه فعلی در قالب RRGGBB#. | |
| isClosingConfirmationEnabled | Boolean | اگر True باشد، هنگامی که کاربر در تلاش برای بستن برنامک است، سوال تایید نمایش داده میشود و اگر False باشد، برنامک بدون سوال بست میشود. | |
| isVerticalSwipesEnabled | Boolean | اگر True باشد, تند کشیدن عمودی برای بستن یا کوچک کردن برنامک فعال است. و اگر False باشد, تند کشیدن عمودی برای بستن یا کوچک کردن برنامک غیرفعال است. در هر صورت، کاربر همچنان می‌تواند با کشیدن سربرگ برنامک، آن را کوچک کرده و ببندد. | |
| BackButton | BackButton | یک شیء برای کنترل دکمه برگشت که در هدر برنامک در رابط کاربری ایتا قابل نمایش است. | |
| MainButton | BottomButton | یک شیء برای کنترل دکمه اصلی که در پایین برنامک در رابط کاربری ایتا نمایش داده میشود. | |
| SettingsButton | SettingsButton | یک شیء برای کنترل آیتم تنظیمات در منو زمینه برنامک در رابط کاربری ایتا. | |
| HapticFeedback | HapticFeedback | یک شیء برای کنترل بازخورد لمسی. | |
| Accelerometer | Accelerometer | یک شیء برای کنترل شتاب سنج . |  |
| DeviceOrientation | DeviceOrientation | یک شیء برای کنترل جهت گیری . | |
| Gyroscope | Gyroscope | یک شیء برای کنترل گردش . | |
| isVersionAtLeast(version) | Function | اگر ورژن کیت توسعه برنامه ایتای کاربر مساوی یا بالاتر از نسخه ارسال شده به‌عنوان پارامتر باشد، True برمی‌گردد. | |
| setHeaderColor(color) | Function | روشی که رنگ هدر برنامه را در قالب RRGGBB# تنظیم می‌کند. همچنین می‌توانید از کلمات کلیدی bg_color و secondary_bg_color استفاده کنید. | |
| setBackgroundColor(color) | Function | روشی که رنگ پس‌زمینه برنامک را در قالب RRGGBB# تنظیم می‌کند. همچنین می توانید از کلمات کلیدی bg_color و secondary_bg_color استفاده کنید. | |
| setBottomBarColor(color) | Function | روشی برای تنظیم کردن نوار پایینی | |
| enableClosingConfirmation() | Function | روشی که زمانی که کاربر در تلاش برای بستن برنامک است، دریافت تاییده برای بسته شدن را فعال می‌کند. | |
| disableClosingConfirmation() | Function | روشی که زمانی که کاربر در تلاش برای بستن برنامک است، دریافت تاییده برای بسته شدن را غیرفعال می‌کند. | |
| enableVerticalSwipes() | Function | روشی که تند کشیدن‌های عمودی را قادر می‌سازد تا برنامک را ببندند یا کوچک کنند. برای راحتی کاربر، توصیه میشود همیشه کشیدن انگشت‌ها را فعال کنید؛ مگر اینکه با حرکات برنامک مغایرت داشته باشند. | |
| disableVerticalSwipes() | Function | روشی که تند کشیدن‌های عمودی را برای بستن یا کوچک کردن برنامک غیرفعال می‌کند. این روش در صورتی مفید است که برنامک شما از حرکات سوایپ استفاده کند که ممکن است با حرکات برای کوچک کردن و بستن برنامه در تضاد باشد. | |
| onEvent(eventType, eventHandler) | Function | روشی که کنترل کننده رویداد برنامه را تنظیم می‌کند. لیست رویدادهای موجود را بررسی کنید. | |
| offEvent(eventType, eventHandler) | Function | روشی که کنترل کننده رویداد از قبل تنظیم شده را حذف می‌کند. | |
| openLink(url[, options]) | Function | روشی که پیوندی را در یک مرورگر خارجی باز می‌کند. با این کار، برنامک بسته نخواهد شد. گزینه‌ها از نوع OpenLinkOptions هستند. توجه داشته باشید که این روش فقط در پاسخ به تعامل کاربر با رابط برنامک (به عنوان مثال یک کلیک در داخل برنامک یا روی دکمه اصلی) قابل فراخوانی است. | |
| openEitaaLink(url) | Function | روشی که لینک ایتا را در داخل برنامه ایتا باز می‌کند. پس از فراخوانی این روش، برنامک بسته نخواهد شد. | |
| showPopup(params[, callback]) | Function | روشی که یک پاپ آپ بومی را نشان می‌دهد که با آرگومان params از نوع PopupParams توصیف شده است. هنگامی که پنجره بازشو بسته شود، برنامک رویداد popupClosed را دریافت می‌کند. اگر مقدار اختیاری callback پاس داده شود، آن تابع callback فراخوانی میشود و مقدار id دکمه فشرده شده به عنوان مقدار اول به تابع پاس داده میشود. | |
| showAlert(message[, callback]) | Function | روشی که message را در یک هشدار ساده با دکمه "بستن" نشان می‌دهد. اگر یک پارامتر callback اختیاری ارسال شده باشد، با بسته شدن پنجره بازشو، تابع callback فراخوانی میشود. | |
| showConfirm(message[, callback]) | Function | روشی که message را در یک پنجره تأیید ساده با دکمه های «OK» و «Cancel» نشان می‌دهد. اگر یک پارامتر callback اختیاری ارسال شده باشد، وقتی پنجره بازشو بسته شود، تابع callback فراخوانی میشود و اولین آرگومان یک بولین است که نشان می‌دهد آیا کاربر دکمه «OK» را فشار داده است یا خیر. | |
| showScanQrPopup(params[, callback]) | Function | روشی که یک پنجره بومی برای اسکن یک کد QR را نشان می‌دهد که با آرگومان params از نوع ScanQrPopupParams توصیف شده است. برنامک رویداد qrTextReceived را هر بار که اسکنر کدی را با داده‌های متنی می‌خواند، دریافت می‌کند. اگر یک پارامتر callback اختیاری ارسال شده باشد، تابع callback فراخوانی میشود و متن کد QR به عنوان اولین آرگومان ارسال میشود. برگرداندن true در داخل این تابع callback باعث بسته شدن پنجره بازشو میشود. | |
| closeScanQrPopup() | Function | روشی که پنجره بومی را برای اسکن یک کد QR باز شده با روش showScanQrPopup می‌بندد. اگر داده‌های معتبری در رویداد qrTextReceived دریافت کرده‌اید، آن را اجرا کنید. | |
| requestWriteAccess([callback]) | Function | روشی که یک پاپ آپ بومی را نشان می‌دهد که برای برنامک جهت ارسال پیام به کاربر درخواست مجوز می‌کند. اگر یک پارامتر callback اختیاری ارسال شده باشد، تابع callback زمانی که پنجره بازشو بسته شود فراخوانی میشود و اولین آرگومان، یک بولین است که نشان می‌دهد آیا کاربر این دسترسی را داده است یا خیر. | |
| requestContact([callback]) | Function | روشی که یک پاپ آپ بومی را نشان می‌دهد که از کاربر شماره تلفن خود را درخواست می‌کند. اگر یک پارامتر callback اختیاری ارسال شده باشد، زمانی که پنجره بازشو بسته شود، تابع callback فراخوانی میشود و اولین آرگومان، یک بولین است که نشان می‌دهد کاربر شماره تلفن خود را به اشتراک گذاشته است یا خیر. دومین آرگومان، یک رشته از داده‌های تماس کاربر به همراه یک هش است که شما می‌توانید همانند initData از صحت آن مطمئن شوید. | |
| ready() | Function | روشی که به برنامه ایتا اطلاع می‌دهد که برنامک، آماده نمایش است. توصیه میشود که این روش را در اسرع وقت و به محض بارگیری تمام عناصر واسط ضروری، فراخوانی کنید. پس از فراخوانی این روش، مکان‌نمای بارگذاری پنهان میشود و برنامک نمایش داده میشود. اگر متد فراخوانی نشود، مکان نگهدار تنها زمانی پنهان میشود که صفحه به طور کامل بارگذاری شود. | |
| expand() | Function | روشی که برنامک را تا حداکثر ارتفاع موجود گسترش می‌دهد. برای اینکه متوجه شوید برنامک تا حداکثر ارتفاع گسترش یافته است یا خیر، به مقدار پارامتر Eitaa.WebApp.isExpanded مراجعه کنید. | |
| close() | Function | روشی که برنامک را می‌بندد. | |
| addToHomeScreen() | Function | روشی که برنامک را به صفحه اصلی دستگاه اضافه می‌کند. | |
| checkHomeScreenStatus | Function | روشی برای بررسی کردن وجود برنامک در صفحه اصلی | |
| lockOrientation() | Function | روشی که قفل چرخش صفحه را فعال می‌کند. | |
| unlockOrientation() | Function | روشی که قفل چرخش صفحه را غیرفعال می‌کند. | |
| exitFullScreen | Function | روشی برای خروج از حالت تمام صفحه | |
| requestFullScreen | Function | روشی برای درخواست حالت تمام صفحه | |
| downloadFile(params) | Function | روشی که درخواست دانلود فایل را نمایش می‌دهد. پارامتر params از نوع DownloadFileParams است. |  |
OpenLinkOptions
| مقدار | نوع | توضیحات |
|---|---|---|
| try_instant_view | Boolean | اختیاری. در صورت امکان تلاش می‌کند مقصد لینک را به‌صورت Instant View نمایش دهد. |
| try_browser | Boolean | اختیاری. اگر true باشد، تلاش می‌کند لینک در مرورگر پیش‌فرض دستگاه باز شود؛ در غیر این صورت رفتار پیش‌فرض کلاینت اعمال میشود. |
ThemeParams
برنامک می‌تواند ظاهر رابط کاربری را طوری تنظیم کند که با اپلیکیشن کاربر ایتا در زمان واقعی مطابقت داشته باشد. این شیء شامل تنظیمات تم فعلی کاربر است:
| مقدار | نوع | توضیحات |
|---|---|---|
| bg_color | String | اختیاری. رنگ پس زمینه در قالب RRGBBB#. همچنین در CSS به عنوان متغیر var(--tg-theme-bg-color) موجود است. |
| text_color | String | اختیاری. رنگ متن اصلی در قالب RRGBBB#. همچنین در CSS به عنوان متغیر var(--tg-theme-text-color) موجود است. |
| hint_color | String | اختیاری. رنگ متن راهنما در قالب RRGBBB#. همچنین در CSS به عنوان متغیر var(--tg-theme-hint-color) موجود است. |
| link_color | String | اختیاری. رنگ پیوند در قالب RRGBBB#. همچنین در CSS به عنوان متغیر var(--tg-theme-link-color) موجود است. |
| button_color | String | اختیاری. رنگ دکمه در قالب RRGBBB#. همچنین در CSS به عنوان متغیر var(--tg-theme-button-color) موجود است. |
| button_text_color | String | اختیاری. رنگ متن دکمه در قالب RRGBBB#. همچنین در CSS به عنوان متغیر var (--tg-theme-button-text-color) موجود است. |
| secondary_bg_color | String | اختیاری. رنگ پس‌زمینه ثانویه در قالب RRGBBB#. همچنین در CSS به عنوان متغیر var(--tg-theme-secondary-bg-color) موجود است. |
| header_bg_color | String | اختیاری. رنگ پس‌زمینه سرصفحه در قالب RRGBBB#. همچنین در CSS به عنوان متغیر var(--tg-theme-header-bg-color) موجود است. |
| accent_text_color | String | اختیاری. رنگ متن در قالب RRGBBB#. همچنین در CSS به عنوان متغیر var(--tg-theme-accent-text-color) موجود است. |
| section_bg_color | String | اختیاری. رنگ پس‌زمینه بخش در قالب RRGBBB#. توصیه میشود از این به همراه secondary_bg_color استفاده کنید. همچنین در CSS به عنوان متغیر var(--tg-theme-section-bg-color) موجود است. |
| section_header_text_color | String | اختیاری. رنگ متن سرصفحه در قالب RRGBBB#. همچنین در CSS به عنوان متغیر var (--tg-theme-section-header-text-color) موجود است. |
| section_separator_color | String | اختیاری. رنگ جداکننده بخش در قالب RRGBBB#. همچنین در CSS به عنوان متغیر var(--tg-theme-section-separator-color) موجود است. |
| subtitle_text_color | String | اختیاری. رنگ متن زیرنویس در قالب RRGBBB#. همچنین در CSS به عنوان متغیر var(--tg-theme-subtitle-text-color) موجود است. |
| destructive_text_color | String | اختیاری. رنگ متن برای اقدامات مخرب در قالب RRGBBB#. همچنین در CSS به عنوان متغیر var (--tg-theme-destructive-text-color) موجود است. |
| bottom_bar_bg_color | String | اختیاری. رنگ پس‌زمینه نوار پایین در قالب RRGGBB#. همچنین به صورت متغیر CSS با نام var(--tg-theme-bottom-bar-bg-color) موجود است. |
PopupParams
| مقدار | نوع | توضیحات |
|---|---|---|
| title | String | اختیاری. متنی که باید در عنوان پنجره نمایش داده شود، بین 0 تا 64 کاراکتر. |
| message | String | الزامی. پیامی که باید در بدنه پنجره نمایش داده شود، بین 1 تا 256 کاراکتر. |
| buttons | PopupButton[] | اختیاری. لیست دکمه‌هایی که در پنجره بازشو نمایش داده می‌شوند (بین 1 تا 3 دکمه). به‌طور پیش‌فرض برابر با [{"type":"close"}] است. |
ScanQrPopupParams
| مقدار | نوع | توضیحات |
|---|---|---|
| text | String | (اختیاری) متنی که زیر عنوان 'اسکن QR' نمایش داده میشود. می‌تواند بین ۰ تا ۶۴ کاراکتر باشد. |
PopupButton
| مقدار | نوع | توضیحات |
|---|---|---|
| id | String | اختیاری. شناسه دکمه، 0-64 کاراکتر. به طور پیش فرض روی رشته خالی تنظیم کنید. اگر دکمه فشار داده شود، شناسه آن در callback و رویداد popupClosed برگردانده میشود. |
| type | String | اختیاری. نوع دکمه به طور پیش فرض روی default تنظیم میشود. می‌تواند یکی از این مقادیر باشد: - default، یک دکمه با سبک پیش‌فرض، - ok، یک دکمه با متن محلی «تایید»، - close، یک دکمه با متن محلی «بستن»، - cancel، یک دکمه با متن محلی "لغو"، - destructive، دکمه‌ای با سبکی که یک عمل مخرب را نشان می‌دهد (مانند "حذف"، "پاک کردن"، و غیره). |
| text | String | اختیاری. متنی که روی دکمه نمایش داده میشود، 0-64 کاراکتر. اگر نوع پیش‌فرض یا مخرب باشد، ضروری است. برای انواع دیگر بی‌ربط است. |
BackButton
| مقدار | نوع | توضیحات |
|---|---|---|
| isVisible | Boolean | نشان می‌دهد که آیا دکمه قابل مشاهده است یا خیر. به طور پیش فرض روی false تنظیم کنید. |
| onClick(callback) | Function | روشی که کنترل کننده رویداد فشار دکمه را تنظیم می‌کند. نام مستعار Eitaa.WebApp.onEvent ('backButtonClicked', callback) |
| offClick(callback) | Function | روشی که کنترل کننده رویداد فشار دکمه را حذف می‌کند. نام مستعار Eitaa.WebApp.offEvent ('backButtonClicked', callback) |
| show() | Function | روشی برای فعال و قابل مشاهده کردن دکمه. |
| hide() | Function | روشی برای مخفی کردن دکمه. |
SettingsButton
| مقدار | نوع | توضیحات |
|---|---|---|
| isVisible | Boolean | نشان می‌دهد که آیا آیتم منوی زمینه قابل مشاهده است یا خیر. به طور پیش فرض روی false تنظیم میشود. |
| onClick(callback) | Function | روشی که کنترل کننده رویداد مطبوعاتی را برای آیتم تنظیمات در منوی زمینه تنظیم می‌کند. نام مستعار ٍEitaa.WebApp.onEvent ('settingsButtonClicked', callback) |
| offClick(callback) | Function | روشی که کنترل کننده رویداد مطبوعاتی را از آیتم تنظیمات در منوی زمینه حذف می‌کند. نام مستعار Eitaa.WebApp.offEvent ('settingsButtonClicked', callback) |
| show() | Function | روشی برای قابل مشاهده کردن مورد تنظیمات در منوی زمینه. |
| hide() | Function | روشی برای پنهان کردن مورد تنظیمات در منوی زمینه. |
HapticFeedBack
| مقدار | نوع | توضیحات |
|---|---|---|
| impactOccurred(style) | Function | یک روش می‌گوید که یک ضربه رخ داده است. برنامه ایتا ممکن است بر اساس مقدار سبک ارسال شده، هاپتیک(واکنش لمسی) مناسب را پخش کند. سبک می‌تواند یکی از این مقادیر باشد: - light، نشان دهنده برخورد بین اشیاء رابط کاربری کوچک یا سبک وزن است، - medium، نشان دهنده برخورد بین اشیاء UI با اندازه متوسط یا وزن متوسط است، - heavy، نشان دهنده برخورد بین اشیاء رابط کاربری بزرگ یا سنگین وزن است، - rigid، نشان دهنده برخورد بین اشیاء رابط کاربری سخت یا غیر قابل انعطاف است، - soft، نشان دهنده برخورد بین اشیاء رابط کاربری نرم یا انعطاف پذیر است. |
| notificationOccurred(type) | Function | یک روش می‌گوید که یک کار یا عمل موفق، شکست خورده است، یا یک هشدار ایجاد کرده است. برنامه ایتا ممکن است بر اساس نوع مقدار ارسال شده، هاپتیک(واکنش لمسی) مناسب را پخش کند. نوع می‌تواند یکی از این مقادیر باشد: - error، نشان می‌دهد که یک کار یا عمل شکست خورده است، - success، نشان می‌دهد که یک کار یا عمل با موفقیت انجام شده است، - warning، نشان می‌دهد که یک کار یا عمل یک هشدار ایجاد کرده است. |
| ()selectionChanged | Function | یک روش می‌گوید که کاربر یک انتخاب را تغییر داده است. برنامه ایتا ممکن است هاپتیک(واکنش لمسی) مناسب را پخش کند. هنگامی که کاربر انتخابی را انجام می‌دهد یا تأیید می‌کند، از این بازخورد استفاده نکنید. فقط زمانی از آن استفاده کنید که انتخاب تغییر کند. |
WebAppInitData
| مقدار | نوع | توضیحات | نسخه کیت |
|---|---|---|---|
| query_id | String | اختیاری. یک شناسه منحصر به فرد برای جلسه برنامه یا برنامک | |
| user | WebAppUser | اختیاری. یک شیء حاوی داده‌های مربوط به کاربر فعلی. | |
| chat_type | String | اختیاری. نوع گفتگویی که برنامک از آن باز شده است. می‌تواند "private"، "group" یا "channelOrSupergroup" باشد. فقط برای برنامک‌های راه اندازی شده از پیوندهای مستقیم بازگردانده میشود. | فقط در برنامک |
| chat_instance | String | اختیاری. یک شناسه یکتا که نشان‌دهنده گفتگویی است که برنامک از آن باز شده است. فقط برای برنامک هایی که با لینک مستقیم باز شده‌اند بازگردانده میشود. | فقط در برنامک |
| start_param | String | اختیاری. مقدار پارامتر start_param نیز در پارامتر GET tgWebAppStartParam ارسال میشود، بنابراین برنامک می‌تواند فوراً رابط صحیح را بارگیری کند. | فقط در برنامک |
| auth_date | Integer | یونیکس تایم زمانی که فرم باز شد. | |
| device_id | String | یک شناسه یکتا که مشخص می‌کند کاربر از چه دستگاهی و با چه حساب ایتایی وارد برنامه یا برنامک شده است. | |
| hash | String | یک هش از تمام پارامترهای ارسال شده که سرور برنامه یا برنامک می‌تواند از آن برای بررسی اعتبار آن‌ها استفاده کند. |
WebAppUser
| مقدار | نوع | توضیحات |
|---|---|---|
| id | Integer | یک شناسه منحصر به فرد برای کاربر ، این عدد ممکن است بیش از 32 بیت مهم داشته باشد و برخی از زبان‌های برنامه نویسی ممکن است در تفسیر آن مشکل/نقص بی‌صدا داشته باشند. حداکثر 52 بیت مهم دارد، بنابراین یک عدد صحیح 64 بیتی یا یک نوع double-precision float برای ذخیره این شناسه امن است. |
| first_name | String | نام کاربر |
| last_name | String | اختیاری. نام خانوادگی کاربر |
| language_code | String | اختیاری. برچسب زبان IETF زبان کاربر. فقط در قسمت user برمی گردد. |
| allows_write_to_pm | True | اختیاری. True، اگر این کاربر به برنامه اجازه داده باشد که برنامه به او پیام دهد. |
SafeAreaInset
| مقدار | نوع | توضیحات |
|---|---|---|
| top | عدد صحیح | فاصله (پدینگ) بالای صفحه به پیکسل که باید برای جلوگیری از هم‌پوشانی با عناصر سیستمی (مثل ناچ یا نوار وضعیت) رعایت شود. همچنین به صورت متغیر CSS با نام var(--tg-safe-area-inset-top) در دسترس است. |
| bottom | عدد صحیح | فاصله پایین صفحه به پیکسل که باید برای جلوگیری از هم‌پوشانی با عناصر سیستمی (مثل نوار ناوبری) رعایت شود. همچنین به صورت متغیر CSS با نام var(--tg-safe-area-inset-bottom) در دسترس است. |
| left | عدد صحیح | فاصله سمت چپ صفحه به پیکسل که باید برای جلوگیری از هم‌پوشانی با عناصر سیستمی رعایت شود. همچنین به صورت متغیر CSS با نام var(--tg-safe-area-inset-left) در دسترس است. |
| right | عدد صحیح | فاصله سمت راست صفحه به پیکسل که باید برای جلوگیری از هم‌پوشانی با عناصر سیستمی رعایت شود. همچنین به صورت متغیر CSS با نام var(--tg-safe-area-inset-right) در دسترس است. |
ContentSafeAreaInset
| مقدار | نوع | توضیحات |
|---|---|---|
| top | عدد صحیح | فاصله (پدینگ) بالای ناحیه محتوای صفحه به پیکسل که باید برای جلوگیری از هم‌پوشانی با عناصر رابط کاربری ایتا رعایت شود. همچنین به صورت متغیر CSS با نام var(--tg-content-safe-area-inset-top) در دسترس است. |
| bottom | عدد صحیح | فاصله پایین ناحیه محتوای صفحه به پیکسل که باید برای جلوگیری از هم‌پوشانی با عناصر رابط کاربری ایتا رعایت شود. همچنین به صورت متغیر CSS با نام var(--tg-content-safe-area-inset-bottom) در دسترس است. |
| left | عدد صحیح | فاصله سمت چپ ناحیه محتوای صفحه به پیکسل که باید برای جلوگیری از هم‌پوشانی با عناصر رابط کاربری ایتا رعایت شود. همچنین به صورت متغیر CSS با نام var(--tg-content-safe-area-inset-left) در دسترس است. |
| right | عدد صحیح | فاصله سمت راست ناحیه محتوای صفحه به پیکسل که باید برای جلوگیری از هم‌پوشانی با عناصر رابط کاربری ایتا رعایت شود. همچنین به صورت متغیر CSS با نام var(--tg-content-safe-area-inset-right) در دسترس است. |
BottomButton
| مقدار | نوع | توضیحات |
|---|---|---|
| type | String | نوع دکمه. می‌تواند main (برای دکمه اصلی) یا secondary (برای دکمه ثانویه) باشد. |
| text | String | متن فعلی دکمه. به طور پیش‌فرض برای دکمه اصلی Continue و برای دکمه ثانویه Cancel است. |
| color | String | رنگ فعلی دکمه. برای دکمه اصلی از themeParams.button_color و برای دکمه ثانویه از themeParams.bottom_bar_bg_color استفاده میشود. |
| textColor | String | رنگ فعلی متن دکمه. برای دکمه اصلی از themeParams.button_text_color و برای دکمه ثانویه از themeParams.button_color استفاده میشود. |
| isVisible | Boolean | نشان می‌دهد که آیا دکمه قابل مشاهده است یا خیر. پیش‌فرض: false. |
| isActive | Boolean | نشان می‌دهد که آیا دکمه فعال است یا خیر. پیش‌فرض: true. |
| hasShineEffect | Boolean | نشان می‌دهد که دکمه افکت درخشش دارد یا نه. پیش‌فرض: false. فقط برای دکمه ثانویه زمانی که هر دو دکمه فعال باشند. |
| position | String | موقعیت دکمه ثانویه. فقط زمانی که هر دو دکمه فعال باشند. مقادیر: left (سمت چپ دکمه اصلی)، right (سمت راست دکمه اصلی)، top (بالای دکمه اصلی)، bottom (پایین دکمه اصلی). پیش‌فرض: left. |
| isProgressVisible | Boolean | فقط خواندنی. نشان می‌دهد که آیا دکمه نشانگر بارگذاری را نمایش می‌دهد یا خیر. |
| setText(text) | Function | متدی برای تنظیم متن دکمه. |
| onClick(callback) | Function | متدی برای ثبت handler رویداد کلیک روی دکمه. معادل: window.Eitaa.WebApp.onEvent('mainButtonClicked', callback) |
| offClick(callback) | Function | متدی برای حذف handler رویداد کلیک روی دکمه. معادل: window.Eitaa.WebApp.offEvent('mainButtonClicked', callback) |
| show() | Function | متدی برای نمایش دکمه. توجه: نمایش دکمه اصلی باعث مخفی شدن دکمه از منوی پیوست میشود. |
| hide() | Function | متدی برای مخفی کردن دکمه. |
| enable() | Function | متدی برای فعال کردن دکمه. |
| disable() | Function | متدی برای غیرفعال کردن دکمه. |
| showProgress(leaveActive) | Function | متدی برای نمایش نشانگر بارگذاری روی دکمه. اگر پارامتر leaveActive مقدار true داشته باشد، دکمه فعال باقی می‌ماند. در غیر این صورت، دکمه غیرفعال میشود. |
| hideProgress() | Function | متدی برای مخفی کردن نشانگر بارگذاری. |
| setParams(params) | Function | متدی برای تنظیم پارامترهای دکمه. پارامتر params یک شیء شامل هر یک از موارد زیر است: text (متن)، color (رنگ دکمه)، text_color (رنگ متن)، is_active (فعال بودن)، is_visible (نمایش)، position (موقعیت دکمه ثانویه)، has_shine_effect (افکت درخشش). |
Accelerometer
| مقدار | نوع | توضیحات | نسخه کیت |
|---|---|---|---|
| isStarted | Boolean | نشان می‌دهد که آیا ردیابی شتاب‌سنج در حال حاضر فعال است یا خیر. | |
| x | Float | شتاب فعلی در محور X بر حسب m/s². | |
| y | Float | شتاب فعلی در محور Y بر حسب m/s². | |
| z | Float | شتاب فعلی در محور Z بر حسب m/s². | |
| start(params[, callback]) | Function | شروع ردیابی داده‌های شتاب‌سنج با پارامتر params از نوع AccelerometerStartParams. اگر callback ارسال شود، پس از شروع موفقیت‌آمیز، با مقدار بولی فراخوانی میشود. | |
| stop([callback]) | Function | توقف ردیابی داده‌های شتاب‌سنج. اگر callback ارسال شود، پس از توقف موفقیت‌آمیز، با مقدار بولی فراخوانی میشود. |
AccelerometerStartParams
| مقدار | نوع | توضیحات |
|---|---|---|
| refresh_rate | Integer | (اختیاری) نرخ تازه‌سازی بر حسب میلی‌ثانیه. مقدار مجاز بین ۲۰ تا ۱۰۰۰ است. مقدار پیش‌فرض ۱۰۰۰ می‌باشد. توجه: ممکن است refresh_rate در همه پلتفرم‌ها پشتیبانی نشود و نرخ واقعی نمونه‌برداری با مقدار مشخص‌شده متفاوت باشد. |
DeviceOrientation
| مقدار | نوع | توضیحات | نسخه کیت |
|---|---|---|---|
| isStarted | Boolean | نشان می‌دهد که آیا ردیابی وضعیت چرخش دستگاه فعال است یا خیر. | |
| absolute | Boolean | مشخص می‌کند که آیا داده‌های وضعیت دستگاه به صورت مطلق ارائه می‌شوند یا خیر. | |
| alpha | Float | چرخش حول محور Z (زاویه آلفا) بر حسب رادیان. | |
| beta | Float | چرخش حول محور X (زاویه بتا) بر حسب رادیان. | |
| gamma | Float | چرخش حول محور Y (زاویه گاما) بر حسب رادیان. | |
| start(params[, callback]) | Function | شروع ردیابی داده‌های وضعیت چرخش دستگاه با پارامتر params از نوع DeviceOrientationStartParams. اگر callback ارسال شود، پس از شروع موفقیت‌آمیز، با مقدار بولی فراخوانی میشود. | |
| stop([callback]) | Function | توقف ردیابی داده‌های وضعیت چرخش دستگاه. اگر callback ارسال شود، پس از توقف موفقیت‌آمیز، با مقدار بولی فراخوانی میشود. |
DeviceOrientationStartParams
| مقدار | نوع | توضیحات |
|---|---|---|
| refresh_rate | Integer | (اختیاری) نرخ تازه‌سازی بر حسب میلی‌ثانیه. مقدار مجاز بین ۲۰ تا ۱۰۰۰ است. مقدار پیش‌فرض ۱۰۰۰ می‌باشد. توجه: ممکن است refresh_rate در همه پلتفرم‌ها پشتیبانی نشود و نرخ واقعی نمونه‌برداری با مقدار مشخص‌شده متفاوت باشد. |
| need_absolute | Boolean | (اختیاری) اگر مقدار true ارسال شود، داده‌های وضعیت مطلق (نسبت به شمال مغناطیسی) دریافت میشود. برای کاربردهایی مانند قطب‌نما این گزینه را فعال کنید. اگر داده نسبی کافی است، مقدار false ارسال کنید (پیش‌فرض: false). |
نکته: برخی دستگاه‌ها ممکن است داده وضعیت مطلق را پشتیبانی نکنند و حتی با مقدار need_absolute=true فقط داده نسبی ارائه دهند. برای تشخیص نوع داده، پارامتر DeviceOrientation.absolute را بررسی کنید.
Gyroscope
| مقدار | نوع | توضیحات | نسخه کیت |
|---|---|---|---|
| isStarted | Boolean | نشان می‌دهد که آیا ردیابی ژیروسکوپ در حال حاضر فعال است یا خیر. | |
| x | Float | نرخ چرخش فعلی حول محور X بر حسب رادیان بر ثانیه (rad/s). | |
| y | Float | نرخ چرخش فعلی حول محور Y بر حسب رادیان بر ثانیه (rad/s). | |
| z | Float | نرخ چرخش فعلی حول محور Z بر حسب رادیان بر ثانیه (rad/s). | |
| start(params[, callback]) | Function | شروع ردیابی داده‌های ژیروسکوپ با پارامتر params از نوع GyroscopeStartParams. اگر callback ارسال شود، پس از شروع موفقیت‌آمیز، با مقدار بولی فراخوانی میشود. | |
| stop([callback]) | Function | توقف ردیابی داده‌های ژیروسکوپ. اگر callback ارسال شود، پس از توقف موفقیت‌آمیز، با مقدار بولی فراخوانی میشود. |
GyroscopeStartParams
| مقدار | نوع | توضیحات |
|---|---|---|
| refresh_rate | Integer | (اختیاری) نرخ تازه‌سازی بر حسب میلی‌ثانیه. مقدار مجاز بین ۲۰ تا ۱۰۰۰ است. مقدار پیش‌فرض ۱۰۰۰ می‌باشد. توجه: ممکن است refresh_rate در همه پلتفرم‌ها پشتیبانی نشود و نرخ واقعی نمونه‌برداری با مقدار مشخص‌شده متفاوت باشد. |
DownloadFileParams
| مقدار | نوع | توضیحات |
|---|---|---|
| url | String | آدرس HTTPS فایل برای دانلود. |
| file_name | String | نام پیشنهادی برای فایل دانلودی. |
رویداد های در دسترس
برنامک می‌تواند رویدادهایی را از برنامه یا برنامک ایتا دریافت کند. می‌توان با استفاده از
روش Eitaa.WebApp.onEvent(eventType, eventHandler) یک handler به آن متصل کرد. در داخل eventHandler شی this به
Eitaa.WebApp اشاره دارد، مجموعه پارامترهای ارسال شده به handler به نوع رویداد بستگی دارد. در زیر لیستی از رویدادهای
احتمالی آمده است:
| نام رویداد (eventType) | توضیحات | نسخه کیت |
|---|---|---|
| themeChanged | هر زمان که تنظیمات تم در برنامه یا برنامک ایتا کاربر تغییر می کند (از جمله تغییر به حالت شب) این رویداد رخ می دهد. eventHandler هیچ پارامتری دریافت نمی کند، تنظیمات تم جدید و طرح رنگ را می توان به ترتیب از طریق this.themeParams و this.colorScheme دریافت کرد. | |
| viewportChanged | این رویداد زمانی رخ می دهد که بخش قابل مشاهده برنامه یا برنامک تغییر کند. eventHandler یک شی با فیلد واحد isStateStable دریافت می کند. اگر isStateStable برابر با true باشد، تغییر اندازه برنامک به پایان رسیده است. اگر false باشد، تغییر اندازه ادامه دارد (کاربر در حال گسترش یا جمع کردن برنامک یا یک شیء متحرک در حال پخش است). مقدار فعلی ارتفاع بخش قابل مشاهده در this.viewportHeight موجود است. | |
| activated | زمانی رخ می‌دهد که برنامه یا برنامک فعال (در فوکوس) میشود (مثلاً از حالت minimize خارج شود یا بین تب‌ها انتخاب شود). eventHandler هیچ پارامتری دریافت نمی‌کند. | |
| deactivated | زمانی رخ می‌دهد که برنامه یا برنامک غیرفعال میشود (مثلاً minimize شود یا به تب غیرفعال برود). eventHandler هیچ پارامتری دریافت نمی‌کند. | |
| safeAreaChanged | زمانی رخ می‌دهد که مقادیر safe area دستگاه تغییر کند (مثلاً به دلیل چرخش یا تغییر ابعاد صفحه). eventHandler هیچ پارامتری دریافت نمی‌کند. مقادیر جدید از طریق this.safeAreaInset قابل دریافت است. | |
| contentSafeAreaChanged | زمانی رخ می‌دهد که safe area ناحیه محتوا تغییر کند (مثلاً به دلیل چرخش یا تغییر ابعاد صفحه). eventHandler هیچ پارامتری دریافت نمی‌کند. مقادیر جدید از طریق this.contentSafeAreaInset قابل دریافت است. | |
| mainButtonClicked | هنگامی که main button فشار داده می شود رخ می دهد. eventHandler هیچ پارامتری دریافت نمی کند. | |
| backButtonClicked | هنگامی که back button فشار داده می شود رخ می دهد. eventHandler هیچ پارامتری دریافت نمی کند. | |
| settingsButtonClicked | زمانی رخ می دهد که مورد تنظیمات در منوی زمینه فشار داده شود. eventHandler هیچ پارامتری دریافت نمی کند. | |
| popupClosed | زمانی رخ می دهد که پنجره پاپ آپ باز شده بسته شود. eventHandler یک شی را با تک فیلد button_id دریافت می کند - مقدار فیلد id دکمه فشرده شده است. اگر هیچ دکمه ای فشار داده نشده باشد، فیلد button_id برابر با null خواهد بود. | |
| qrTextReceived | زمانی اتفاق می‌افتد که اسکنر QR کدی را با داده‌های متنی می‌گیرد. eventHandler یک شی را با تک فیلد data حاوی داده های متنی از QR دریافت می کند. | |
| scanQrPopupClosed | زمانی رخ می دهد که پنجره بازشو اسکنر QR توسط کاربر بسته شود. eventHandler هیچ پارامتری دریافت نمی کند. | |
| writeAccessRequested | زمانی رخ می دهد که مجوز نوشتن درخواست شده باشد. eventHandler یک شی را با تک فیلد status دریافت می‌کند که یکی از وضعیت‌های زیر را شامل میشود: - allowed - کاربر به برنامه اجازه نوشتن داده است، - cancelled – کاربر این درخواست را رد کرد. | |
| contactRequested | زمانی رخ می دهد که شماره تلفن کاربر درخواست شده باشد. eventHandler یک شی را با تک فیلد status دریافت می‌کند که یکی از وضعیت‌های زیر را شامل میشود: - sent – کاربر شماره تلفن خود را با برنامه به اشتراک گذاشت، - cancelled – کاربر این درخواست را رد کرد. | |
| fullscreenChanged | زمانی رخ می‌دهد که برنامه یا برنامک وارد یا خارج از حالت تمام‌صفحه شود. eventHandler هیچ پارامتری دریافت نمی‌کند. وضعیت فعلی از طریق this.isFullscreen قابل بررسی است. | |
| fullscreenFailed | اگر تلاش برای ورود به حالت تمام‌صفحه شکست بخورد، این رویداد رخ می‌دهد. eventHandler شیئی با فیلد error دریافت می‌کند که علت خطا را توضیح می‌دهد (مانند UNSUPPORTED یا ALREADY_FULLSCREEN). | |
| homeScreenAdded | زمانی رخ می‌دهد که برنامه یا برنامک با موفقیت به صفحه اصلی اضافه شود. eventHandler هیچ پارامتری دریافت نمی‌کند. | |
| homeScreenChecked | پس از بررسی وضعیت صفحه اصلی رخ می‌دهد. eventHandler شیئی با فیلد status دریافت می‌کند که وضعیت فعلی را نشان می‌دهد (مانند unsupported, unknown, added, missed). |