walnut-web-app
TypeScript icon, indicating that this package has built-in type declarations

6.4.0 • Public • Published

build npm cdnjs minified size license

walnut-web-app

Bring your WebApp into effect outside of Telegram WebView.

Table of Contents

General Information

This package achieves something otherwise impossible by intervening between WebView and WebApp. It makes the testing process significantly smoother.

Schematic

I would greatly appreciate it if you could create a drawing for me, especially if it's done with more skill.

Setup

$ npm i -D walnut-web-app

Usage

To ensure proper operation, walnut-web-app must be imported before Telegram. This is because it alters the location.hash to enable the WebApp to function outside of Telegram WebView.

// destructured import
import { utils, event } from 'walnut-web-app'
// import all exported members
import * as walnut from 'walnut-web-app'
// import default export
import walnut from 'walnut-web-app'

Here are two options for using walnut-web-app:

  1. Simply import the package without any additional configurations (utilizing the default settings):
// main.js
import 'walnut-web-app'
import 'miku-web-app' // import Telegram
import router from '@/router'
import App from './App.vue'
  1. Import the package and make custom configurations:
// main.js
import '@/walnut'
import 'miku-web-app' // import Telegram
import router from '@/router'
import App from './App.vue'
// src/walnut/index.js
import walnut from 'walnut-web-app'

// default settings
walnut.utils.setup({
  Data: {
    user: {
      id: 127355800,
      first_name: '初音',
      last_name: 'ミク',
      username: 'miku3920',
      language_code: 'zh-hant',
    },
    auth_date: Date.now(),
    token: '1234567890:ABCDEFGHIJKLMNOPQRSTUVWXYZ',
  },
  Version: '6.4',
  Platform: 'tdesktop',
  ThemeParams: {
    bg_color: '#ffffff',
    button_color: '#40a7e3',
    button_text_color: '#ffffff',
    hint_color: '#999999',
    link_color: '#168acd',
    text_color: '#000000',
  },
  Debug: true,
})

walnut.event.on('default', (e) => {
  console.log('[Walnut.default] postEvent', e.type, e.data)
})

walnut.event.on('all', (e) => {
  // do no things
})

Configuration

Customize settings as desired: If you don't specify any settings, the default values will be used.

setup

This technique allows you to lock in a specific time:

walnut.utils.setup({
  Data: {
    auth_date: 1658213143920,
  }
})
Field Type Description
Data SetupData Optional. This object contains data that is transferred to the Web App when it is opened.
Version String Optional. The version of the Bot API available in the user's Telegram app. Set to 6.4 by default.
Platform String Optional. The name of the platform of the user's Telegram app. Set to tdesktop by default.
ThemeParams ThemeParams Optional. Web Apps can adjust the appearance of the interface to match the Telegram user's app in real time. This object contains the user's current theme settings.
Debug Boolean Optional. Make the MainButton visible outside of Telegram WebView. Set to true by default.

SetupData

Field Type Description
query_id string Optional. A fake unique identifier for the Web App session. Messages cannot be sent via the answerWebAppQuery method.
user WebAppUser Optional. An object containing data about the current user.
receiver WebAppUser Optional. An object containing data about the chat partner of the current user in the chat where the bot was launched via the attachment menu.
chat WebAppChat Optional. An object containing data about the chat where the bot was launched via the attachment menu.
start_param string Optional. The value of the startattach parameter, passed via link.
can_send_after number Optional. Fake time in seconds. Message cannot be sent via the answerWebAppQuery method for any length of time.
auth_date number Optional. Unix time when the form was opened.
token string Optional. Any token that is the same as you use for server-side validation

event

If no event handler is set, the default event handler will be used to handle all events. The all event handler, on the other hand, will handle all events, regardless of the specific event handler being set or not.

If you want to trigger the original event, use the e.post() method:

walnut.event.on('all', (e) => {
  e.post()
})

// e.post inside of Telegram WebView
TelegramWebviewProxy.postEvent(e.type, e.data)

// e.post outside of Telegram WebView
console.log('[Walnut.debug] postEvent', e.type, e.data)
eventType
default
all
web_app_setup_closing_behavior
web_app_set_header_color
web_app_set_background_color
web_app_setup_back_button
web_app_setup_main_button
web_app_trigger_haptic_feedback
web_app_data_send
web_app_open_link
web_app_open_tg_link
web_app_open_invoice
web_app_open_popup
web_app_open_scan_qr_popup
web_app_close_scan_qr_popup
web_app_read_text_from_clipboard
web_app_ready
web_app_expand
web_app_close
web_app_request_theme
web_app_request_viewport

Contact

Created by @miku3920. Feel free to contact me if you have any questions or run into any issues!

Package Sidebar

Install

npm i walnut-web-app

Weekly Downloads

29

Version

6.4.0

License

MIT

Unpacked Size

212 kB

Total Files

40

Last publish

Collaborators

  • miku3920