Package: mini-apps
Event Telegram Mini-App DemoThis is a demo of telegram mini apps.It shows a list of events the user can attend and uses websockets to dynamically
update information to the client.InstallationBot SetupYou need to have a bot for mini apps to work. Talk toBotFatherto create the bot. Make sure you enable inline mode and the menu button in the
bot settings.Use/newappto create a web app on the bot and give iteventsas short name.Also, do keep track of the bot token as it's needed in the server
configuration file.Installation OverviewThis project consists of a server-side app written in python that is exposed
as a web socket, and a static html page that communicates with the web socket.They both have a JSON with settings so you can configure it to your needs.The following guide shows how to install and configure the various tools
on a Ubuntu server with Apache.This gues assumes the domain isminiapps.example.com, replace with the
appropriate value in the various config files.Most steps require to have root access on a default configuration, if you are
not logged in asroot, you can trysudo.This guide will install the mini app in/var/www/miniapps.example.com,
you might want to use a different directory.Installing DependenciesWe need Apache to run the web server, docker-compose to run
the web socket code.aptinstall-ydocker-composegitConfigurationEnsure the project is installed in a directory that apache can serve,If you want to use git to install the project, use the following commands:cd/var/www/
gitclonehttps://github.com/mbasaglia/mini_apps.gitminiapps.example.comAdd the settings file for the client/var/www/miniapps.example.com/client/settings.jsonwith the following content:{"socket":"wss://miniapps.example.com/wss/"}And the server-side settings file/var/www/miniapps.example.com/server/settings.jsonwith the following:{"database":{"class":"SqliteDatabase","database":"db/db.sqlite"},"websocket":{"hostname":"localhost","port":2536},"apps":{"mini_event":{"class":"mini_apps.apps.mini_event.MiniEventApp","bot-token":"(your bot token)","api-id":"(your api id)","api-hash":"(your api hash)","url":"https://miniapps.example.com/mini_event/","media-url":"https://miniapps.example.com/"}}}Explanation of the settings fields:database: This configures the database connectionclass: One of thePeewee database classesThe rest of the properties here are passed as class constructor argumentswebsocket: Web socket settingshostname: Socket bind host name or addressport: Socket portapps: Map of app short name to app settings. App settings contain the following:class: Python class that runs the bot / appapi-id: MTProto API ID, you can get its value fromhttps://my.telegram.org/appsapi-hash: MTProto API hash, you can get its value fromhttps://my.telegram.org/appssession: (Optional)session namefor Telethonbot-token: Bot API token as kiven by BotFatherurl: URL of the mini app main pagemedia-url: Base URL for imagesIf you want to run on the Telegram test server, add the following toapps.mini_eventin the JSON,
with the values fromhttps://my.telegram.org/apps."server":{"dc":2,"address":"127.0.0.1","port":443}PermissionsThe media directory in the client needs to be writable by the web server:chgrpwww-data/var/www/miniapps.example.com/client/media/
chmodg+w/var/www/miniapps.example.com/client/media/Running DockerThere is a docker-compose file that wraps the all services as containers.To start the container simply run the following:cd/var/www/var/www/miniapps.example.com
docker-composeup-dThis will make the app accessible fromhttp://localhost:2537/. You might want to add a web server on top of it
to expose it to the public with your domain name and set up TLS certificates for a secure connection.If you want to install the apps on your machine directly (without docker)
you can follow the instructions for anadvanced installation.Known LimitationsThe events app is a technical demo, for a fully functional app some changes are needed.For one the events are only specified as a time (not a date), this allows the bot
to always show events without having to set up many events throughout the course
of several days.The bot notifies users that registered as attendding an event, this is done
based on the server time (which is in Germany).The live database might get wiped and recreated periodically so some data will
be deleted.More AppsThis guide installs themini_eventapp, which serves as a demo of the mini apps system.To make your own mini app, seeMaking Your Own Apppage.Initial DataThere are a couple of server-side scripts that allow you to add some data into the system:server/add_event.py-ttitle-ddescription-sstart-time-rduration-iimageThis is used to add more events to the database, you pass the image by path
and it will be copied over to the media directory. Note that images should
be less that 512 KB in size, have a 16:9 aspect ratio and should be at least 400 pixels wide.server/list_users.pyShows a list of users, with their telegram ID, admin status and name.server/make_admin.pytelegram-idMakes a user an admin (creating the user if it doesn't exist).
You can useserver/list_users.pyto find the right telegram ID.All these scripts support the--helpcommand that gives more details on how they work.If you want to run these on the docker instance, they should be invoked like this:dockerexec-timini_apps_miniapp_1server/list_users.pyIf you want to run them directly, you need to ensure you have Python
and the pip requirements fromserver/requirements.txtinstalled.Please note that this demo uses SQLite to minimize set up, you might need to restart the server after changing data
from the database.Admin InterfaceIf you created admin users (withserver/make_admin.py), when those users
access the mini app, they will see additional options, which allows them to manage
the events.Web Socket MessagesThis section will describe the messages sent through web sockets.
All the messages are JSON-encoded, and have atypeattribute that determintes
the kind of message.Messages sent from the client, have anappattribute to identify which app the message is delivered to.Connection-related messages:connect: Sent by the server on connection, notifies the client the server can accept messageslogin: Sent by the client, including the telegam mini app authentication datadisconnect: Sent by the server if theloginfailedwelcome: Sent by the server if theloginsucceeded, this includes the telegram id and nameerror: Sent by the server to notify the client of some kind of error. It includes the error message.Messages specific to the Mini Event data:event: Sent by the server when there is a new event available
(or an existing event has been modified). It's also sent after welcome to give all the existing events.
This includes all the event-specific data.attend: Sent by the client to register attendance to an event, it includes the event ID.leave: Sent by the client to cancel attendance to an event, it includes the event ID.LicenseGPLv3+https://www.gnu.org/licenses/gpl-3.0.en.html