Skip to content

Latest commit

 

History

History
195 lines (125 loc) · 11.9 KB

README.md

File metadata and controls

195 lines (125 loc) · 11.9 KB
Raw

Telegram Onboarding Kit

Telegram Onboarding Kit is a simple-to-use tool for crafting onboardings and paywalls for Telegram Bots. You can create pretty onboardings with minimal adjustments to our presets or easily create your own custom flows with our web components – thanks to Telegram Mini Apps.

But why do you need it? Because onboarding/paywall is a must-have attribute of any mobile app – it offers a bright product presentation and seamless payment process. We believe Telegram Mini Apps will be used by millions of users in the future and this kit will help developers to turn their apps into real products!

To start:

  • Have a look at live demo:
  • Watch tutorial: YouTube | Watch Tutorial
  • And check out video demo:
demo.mp4

Features

  • Native support for images, videos, Telegram (.tgs) animated stickers, forms, feature lists and page navigation
  • Configurable products on paywall
  • One-click 0$ deploy on GitHub Pages
  • Auto adaptation to Telegram color scheme
  • Telegram Payments & 👛 Wallet Pay payment methods
  • Large library of UI components for custom builds
  • Language and currency localization
  • Buttons with haptic feedback
  • Content pre-loading for smooth user experience
  • Telegram-native design
  • Many examples/presets (with free-to-use Figma project)
  • Extensive documentation with visual examples
  • MIT License (free for commercial use)

Quick Start

For a quick start you can watch video tutorial: YouTube | Watch Tutorial

But if you prefer text:

  1. Fork this repository and clone it to your local machine
  2. Run command npm ci to install all the dependencies (make sure that you have installed pip and node on your machine)
  3. And now you're ready to run the app with npm run dev command
  4. To run python bot put your tokens to bot/.env (use bot/example.env as an example). Then start the bot with npm run bot command

Onboarding/Paywall configuration

The heart of this project lies in the configuration. By tweaking the configuration file, you can customize the onboarding experience according to your project's requirements. The configuration file can be found at config.ts.

For detailed information on configuring the app, refer to the Configuration Guide.

Integrate onboarding into your bot

The perfect location for onboarding is right at the start of the bot. It will help you to brightly present your product to the user.

To integrate onboarding to your bot, you simply need to add a button with a link of your deployed onboarding web application. Telegram currently supports six different ways of launching Mini Apps. For onboadring launching we recommend using MenuButton or KeyboardButton.

MenuButton

MenuButton is a special button which appears on the left side of the text input (see @DurgerKingBot). This button can be configured without any server code in @BotFather:

  • Go to @BotFather → /mybots → Select yout bot → Bot Settings → Menu Button → Send your onboarding URL → Send button title (e.g. "Onboarding")

Now Menu Button with onboarding will appear in your bot.

KeyboardButton

Try KeyboardButton in action in our Demo Bot. It utilizes Telegram's KeyboardButton with Mini App URL inside.

Here's a snippet for reply_markup implemented with python-telegram-bot library (see full implementation in bot.py):

reply_markup = telegram.ReplyKeyboardMarkup.from_button(
   telegram.KeyboardButton(
      text="🌈 Onboarding",
      web_app=telegram.WebAppInfo(url={ONBOARDING_URL})
   )
)

Note: KeyboardButton does't send any user data to Mini App (e.g. language_code). But you can send all the required data with HTTP GET parameters (see this function as reference).

Adding payments

Good ending of onboarding is a paywall: User selects a product → Chooses payment method → Gets invoice in the chat. After the paywall the bot receives data about the selected product like:

{
   "title": "Title",
   "description": "Description",
   "price": 5.99,
   "currency": "USD",
   "payment_method": "wallet_pay"
}

This data is used for ivoice generation. We implemented 2 different payment methods: native Telegram Payments and 👛 Wallet Pay (but generally any payment method can be integrated into such flow). You can find full code in bot.py:

🌈 Examples/Presets

To help you understand how to create your own configuration, we provide multiple example applications in the ./examples directory. Each example demonstrates different onboarding scenarios and includes a sample configuration file:

  1. Base App

    • Located in: ./app
    • Key features: various slide configurations telegram-native design onboarding from demo video
    • Run command: npm run dev

  2. Fashion AI App

    • Located in: ./examples/ai
    • Key features: interactive slides currency configuration vertical products on paywall custom preset
    • Run command: npm run dev:ai

  3. Meditation App

    • Located in: ./examples/meditation
    • Key features: localization custom icons different image styles custom preset
    • Run command: npm run dev:meditation

  4. AI Tales App

    • Located in: ./examples/tales
    • Key features: language/currency localization interactive flow on onboarding custom preset
    • Run command: npm run dev:tales

  5. VPN App

    • Located in: ./examples/vpn
    • Key features: app created during YouTube tutorial using base preset
    • Run command: npm run dev:vpn

  6. ChatGPT App

    • Located in: ./examples/chatgpt
    • Key features: onboarding for real bot @chatgpt_karfly_bot videos
    • Run command: npm run dev:chagpt

Reusable Packages

@tok/ui

A collection of essential UI components. Explore the potential of these components by visiting our Figma project, where you can see them in action and gain a better understanding of their capabilities.

@tok/telegram-ui

This package offers a convenient wrapper around the @twa-dev/sdk, providing Vue-like components and use-case solutions for Popups, MainButton, BackButton, and Theme integration.

@tok/i18n

A minimalistic package for handling localization in your applications. We refrain from using third-party solutions due to concerns about the bundle sizes they introduce. While we provide this solution, feel free to replace it with your own if it better suits your needs.

@tok/generation

The primary package for generating projects via a configuration file. It offers presets that can be easily extended within the configuration file.

Tools:

@tok/compress

A Node solution for image compression. It processes PNG, JPG, and JPEG files, compressing them and converting them into WEBP, PNG, JPG, or JPEG formats.

@tok/eslint-config

A basic ESLint configuration for vue projects to maintain clean and consistent code.

@tok/tsconfig

Shared tsconfig.base.json file for vue + vite projects

3rd party packages:

Turborepo

A package for managing a monorepository. If you haven't heard of it, take a look at its documentation; it's worth it

Vite

A package for building and running modern web applications. Documentation

Vue

Vue is a JavaScript framework for building user interfaces. Documentation

@twa-dev/sdk

NPM package for Telegram Mini Apps SDK. Take a look at their GitHub repository

Lottie-web

Lottie is a mobile library for Web that parses Adobe After Effects animations exported as json with Bodymovin and renders them natively!

For information on how sticker.tgs files are rendered in this project, please refer to this link

Our team

License

This project is licensed under the MIT License - see the LICENSE file for details.