walnut-web-app

Bring your WebApp into effect outside of Telegram WebView.

Table of Contents

• General Information
• Setup
• Usage
• Configuration
• Contact

General Information

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

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'

2. 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!