mirror of
https://github.com/MarshalX/telegram-crawler.git
synced 2024-12-13 02:11:00 +01:00
276 lines
22 KiB
HTML
276 lines
22 KiB
HTML
<!DOCTYPE html>
|
|
<html class="">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<title>Web events</title>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<meta property="description" content="How telegram apps interact with webpages">
|
|
<meta property="og:title" content="Web events">
|
|
<meta property="og:image" content="">
|
|
<meta property="og:description" content="How telegram apps interact with webpages">
|
|
<link rel="icon" type="image/svg+xml" href="/img/website_icon.svg?4">
|
|
<link rel="apple-touch-icon" sizes="180x180" href="/img/apple-touch-icon.png">
|
|
<link rel="icon" type="image/png" sizes="32x32" href="/img/favicon-32x32.png">
|
|
<link rel="icon" type="image/png" sizes="16x16" href="/img/favicon-16x16.png">
|
|
<link rel="alternate icon" href="/img/favicon.ico" type="image/x-icon" />
|
|
<link href="/css/bootstrap.min.css?3" rel="stylesheet">
|
|
|
|
<link href="/css/telegram.css?234" rel="stylesheet" media="screen">
|
|
<style>
|
|
</style>
|
|
</head>
|
|
<body class="preload">
|
|
<div class="dev_page_wrap">
|
|
<div class="dev_page_head navbar navbar-static-top navbar-tg">
|
|
<div class="navbar-inner">
|
|
<div class="container clearfix">
|
|
<ul class="nav navbar-nav navbar-right hidden-xs"><li class="navbar-twitter"><a href="https://twitter.com/telegram" target="_blank" data-track="Follow/Twitter" onclick="trackDlClick(this, event)"><i class="icon icon-twitter"></i><span> Twitter</span></a></li></ul>
|
|
<ul class="nav navbar-nav">
|
|
<li><a href="//telegram.org/">Home</a></li>
|
|
<li class="hidden-xs"><a href="//telegram.org/faq">FAQ</a></li>
|
|
<li class="hidden-xs"><a href="//telegram.org/apps">Apps</a></li>
|
|
<li class="active"><a href="/api">API</a></li>
|
|
<li class=""><a href="/mtproto">Protocol</a></li>
|
|
<li class=""><a href="/schema">Schema</a></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="container clearfix">
|
|
<div class="dev_page">
|
|
<div id="dev_page_content_wrap" class=" ">
|
|
<div class="dev_page_bread_crumbs"><ul class="breadcrumb clearfix"><li><a href="/api" >API</a></li><i class="icon icon-breadcrumb-divider"></i><li><a href="/api/web-events" >Web events</a></li></ul></div>
|
|
<h1 id="dev_page_title">Web events</h1>
|
|
|
|
<div id="dev_page_content"><!-- scroll_nav -->
|
|
|
|
<p>When interacting with HTML5 games, websites of payment gateways and <a href="/api/bots/webapps">bot web apps</a>, Telegram apps should expose APIs to allow receiving data and events from the websites.</p>
|
|
<h3><a class="anchor" href="#event-apis" id="event-apis" name="event-apis"><i class="anchor-icon"></i></a>Event APIs</h3>
|
|
<p>Games, payment gateways and <a href="/api/bots/webapps">bot web apps</a> can generate events that are meant to be received by the Telegram apps.
|
|
Typically events are generated by using the <code>postEvent</code> method of the <a href="https://github.com/TelegramMessenger/GamingCommunication/blob/master/games.js">GamingCommunication library</a>, or by the <a href="/bots/webapps#initializing-web-apps">bot web apps library</a>.<br>
|
|
The <code>postEvent</code> function will try sending the event to the Telegram app in a number of different ways.</p>
|
|
<h4><a class="anchor" href="#webviewproxy" id="webviewproxy" name="webviewproxy"><i class="anchor-icon"></i></a>WebviewProxy</h4>
|
|
<p>In mobile apps, the event receiver API should be typically exposed as a <code>window.TelegramWebviewProxy</code> object with a <code>postEvent</code> method.</p>
|
|
<pre><code>window.TelegramWebviewProxy.postEvent(eventType, eventData)</code></pre>
|
|
<h4><a class="anchor" href="#windowexternal" id="windowexternal" name="windowexternal"><i class="anchor-icon"></i></a>window.external</h4>
|
|
<p>Alternatively, a <code>window.external.notify</code> method can be exposed, accepting a string JSON payload with the event type and payload:</p>
|
|
<pre><code>window.external.notify(JSON.stringify({eventType: eventType, eventData: eventData}));</code></pre>
|
|
<h4><a class="anchor" href="#postmessage-api" id="postmessage-api" name="postmessage-api"><i class="anchor-icon"></i></a>postMessage API</h4>
|
|
<p>Finally, web MTProto clients that need to open a game, open a <a href="/api/bots/webapps">bot web app</a> or process a payment in an iframe can use the <a href="https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage">postMessage API</a> to receive events from iframes.<br>
|
|
The GamingCommunication and bot web apps libraries by default will use <code>'*'</code> as <code>targetOrigin</code>, sending messages to parent pages regardless of the origin of the embedder.</p>
|
|
<pre><code>window.parent.postMessage(JSON.stringify({eventType: eventType, eventData: eventData}), targetOrigin);</code></pre>
|
|
<h3><a class="anchor" href="#event-types" id="event-types" name="event-types"><i class="anchor-icon"></i></a>Event types</h3>
|
|
<p><code>eventType</code> is a simple string indicating the event type, and <code>eventData</code> is a payload with an object that will be parsed by the Telegram app.</p>
|
|
<h4><a class="anchor" href="#web-app-close" id="web-app-close" name="web-app-close"><i class="anchor-icon"></i></a><code>web_app_close</code></h4>
|
|
<p>No event payload. </p>
|
|
<p>Emitted by <a href="/api/bots/webapps">bot web apps</a> when the web app webview should be closed.</p>
|
|
<h4><a class="anchor" href="#web-app-open-popup" id="web-app-open-popup" name="web-app-open-popup"><i class="anchor-icon"></i></a><code>web_app_open_popup</code></h4>
|
|
<p>Event data: a JSON object with the following fields (which should be properly validated by the client).</p>
|
|
<ul>
|
|
<li><code>title</code> - Title for the popup (optional string, max 64 characters)</li>
|
|
<li><code>message</code> - Message of the popup (string, max 256 characters)</li>
|
|
<li><code>buttons</code> - An array of the following objects (array of 1-3 objects)<ul>
|
|
<li><code>type</code> - Button type (string, one of <code>ok</code>, <code>close</code>, <code>cancel</code>, <code>default</code>, <code>destructive</code> (in this case, the button must be red))</li>
|
|
<li><code>text</code> - Button text (string, optional for <code>ok</code>, <code>close</code> and <code>cancel</code> types)</li>
|
|
<li><code>id</code> - Button ID (unique string)</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<p>Emitted by <a href="/api/bots/webapps">bot web apps</a> when to open a native pop-up over the webview.</p>
|
|
<p>By default, buttons should be displayed on one row.<br>
|
|
If the web app provides two buttons that can't fit horizontally on one row, display each button on a separate row.<br>
|
|
If the web app provides three buttons, always display each button on a separate row. </p>
|
|
<ul>
|
|
<li>If the user presses any of the buttons, call <code>window.Telegram.WebView.receiveEvent("popup_closed", {"button_id": "<button id>"})</code></li>
|
|
<li>If the user cancels the interaction without pressing any of the specified buttons, call <code>window.Telegram.WebView.receiveEvent("popup_closed", {})</code></li>
|
|
</ul>
|
|
<p>Disable handling of this event if a popup is already being displayed, re-enable handling only after the <code>popup_closed</code> response event is emitted.<br>
|
|
While handling is enabled, maximum 3 consecutive valid events of this type can be handled in a timespan of 3 seconds, ignore excess events. </p>
|
|
<h4><a class="anchor" href="#web-app-setup-closing-behavior" id="web-app-setup-closing-behavior" name="web-app-setup-closing-behavior"><i class="anchor-icon"></i></a><code>web_app_setup_closing_behavior</code></h4>
|
|
<p>Event data: a JSON object with a boolean <code>need_confirmation</code>.</p>
|
|
<p>If equal to <code>true</code>, the client should require user confirmation with a "Changes that you made may not be saved." popup with "Cancel"/"Close anyway" buttons before closing the webview, to avoid accidentally aborting a sensitive operation; otherwise no confirmation should be requested. </p>
|
|
<h4><a class="anchor" href="#web-app-set-background-color" id="web-app-set-background-color" name="web-app-set-background-color"><i class="anchor-icon"></i></a><code>web_app_set_background_color</code></h4>
|
|
<p>Event data: a JSON object with a string <code>color</code> with a hex RGB color. </p>
|
|
<p>Used to set the web app background and lower overscroll color. </p>
|
|
<h4><a class="anchor" href="#web-app-set-header-color" id="web-app-set-header-color" name="web-app-set-header-color"><i class="anchor-icon"></i></a><code>web_app_set_header_color</code></h4>
|
|
<p>Event data: a JSON object with a string <code>color_key</code>, with of the following values:</p>
|
|
<ul>
|
|
<li><code>bg_color</code> - The <code>bg_color</code> from the <a href="/api/bots/webapps#theme-parameters">theme parameters</a> should be used.</li>
|
|
<li><code>secondary_bg_color</code> - The <code>secondary_bg_color</code> from the <a href="/api/bots/webapps#theme-parameters">theme parameters</a> should be used.</li>
|
|
</ul>
|
|
<p>Used to set the web app header and upper overscroll color. </p>
|
|
<h4><a class="anchor" href="#web-app-data-send" id="web-app-data-send" name="web-app-data-send"><i class="anchor-icon"></i></a><code>web_app_data_send</code></h4>
|
|
<p>Event data: a JSON object with a string <code>data</code> field. </p>
|
|
<p>Used by <a href="/api/bots/webapps#simple-web-apps">simple webapps</a> to send back data to the bot as specified <a href="/api/bots/webapps#simple-web-apps">here »</a>. The Web App will be closed. </p>
|
|
<h4><a class="anchor" href="#web-app-trigger-haptic-feedback" id="web-app-trigger-haptic-feedback" name="web-app-trigger-haptic-feedback"><i class="anchor-icon"></i></a><code>web_app_trigger_haptic_feedback</code></h4>
|
|
<p>Event data: a JSON object with the following fields:</p>
|
|
<ul>
|
|
<li><code>type</code> - One of the following values (string):<ul>
|
|
<li><code>impact</code> - An impact occurred.</li>
|
|
<li><code>notification</code> - A task or action has succeeded, failed, or produced a warning.</li>
|
|
<li><code>selection_change</code> - The user has changed a selection.</li>
|
|
</ul>
|
|
</li>
|
|
<li><code>impact_style</code> - Only for <code>impact</code> feedbacks, one of the following values (string):<ul>
|
|
<li><code>light</code> - Indicates a collision between small or lightweight UI objects</li>
|
|
<li><code>medium</code> - Indicates a collision between medium-sized or medium-weight UI objects</li>
|
|
<li><code>heavy</code> - Indicates a collision between large or heavyweight UI objects</li>
|
|
<li><code>rigid</code> - Indicates a collision between hard or inflexible UI objects</li>
|
|
<li><code>soft</code> - Indicates a collision between soft or flexible UI objects</li>
|
|
</ul>
|
|
</li>
|
|
<li><code>notification_type</code> - Only for <code>notification</code> feedbacks, one of the folowing values (string):<ul>
|
|
<li><code>error</code> - Indicates that a task or action has failed</li>
|
|
<li><code>success</code> - Indicates that a task or action has completed successfully</li>
|
|
<li><code>warning</code> - Indicates that a task or action produced a warning</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<p>Used to trigger haptic feedback for a user interaction in a webapp.</p>
|
|
<h4><a class="anchor" href="#web-app-open-link" id="web-app-open-link" name="web-app-open-link"><i class="anchor-icon"></i></a><code>web_app_open_link</code></h4>
|
|
<p>Event data: a JSON object with a string <code>url</code> field. </p>
|
|
<p>Used to open a link in an external browser (or in a new tab for browser clients). The Web App will not be closed. </p>
|
|
<p>Note that this method can be called only in response to the user interaction with the Web App interface (e.g. a click inside the Web App or on the main button).<br>
|
|
After opening the URL, further events of this type should be ignored until the user interacts again with the Web App interface (as above).<br>
|
|
Note that user interactions must have a TTL of 10 seconds: events of this type must be ignored if the last Web App user interaction happened more than 10 seconds ago.</p>
|
|
<h4><a class="anchor" href="#web-app-open-tg-link" id="web-app-open-tg-link" name="web-app-open-tg-link"><i class="anchor-icon"></i></a><code>web_app_open_tg_link</code></h4>
|
|
<p>Event data: a JSON object with a string <code>path_full</code> field, containing the path+query component of a <a href="/api/links">t.me deep link</a> (<code>url = 'https://t.me' + path_full</code>). </p>
|
|
<p>Used to open a <a href="/api/links">t.me deep link</a>. The Web App must be closed.</p>
|
|
<h4><a class="anchor" href="#web-app-open-invoice" id="web-app-open-invoice" name="web-app-open-invoice"><i class="anchor-icon"></i></a><code>web_app_open_invoice</code></h4>
|
|
<p>Event data: a JSON object with a string <code>slug</code> field, containing an <a href="/api/links#invoice-links">invoice deep link</a>.</p>
|
|
<p>Used to initiate <a href="/api/payments">payment of an invoice »</a>, by opening an invoice popup over the Web App: the Web App itself must not be closed. </p>
|
|
<p>The payment status must be reported back to the web app using <a href="/api/bots/webapps#invoice-closed">invoice_closed</a>.</p>
|
|
<h4><a class="anchor" href="#web-app-expand" id="web-app-expand" name="web-app-expand"><i class="anchor-icon"></i></a><code>web_app_expand</code></h4>
|
|
<p>No event payload.</p>
|
|
<p>Expands the web app to the maximum available height.<br>
|
|
The web app must also be expanded when the user swipes up on the webview. </p>
|
|
<p>This event must be ignored <em>during</em> a user swipe down, used to reduce the webview.</p>
|
|
<h4><a class="anchor" href="#web-app-request-viewport" id="web-app-request-viewport" name="web-app-request-viewport"><i class="anchor-icon"></i></a><code>web_app_request_viewport</code></h4>
|
|
<p>No event payload.</p>
|
|
<p>Used by web apps to request information about the viewport, clients should emit a <a href="/api/bots/webapps#viewport-changed">viewport_changed event</a>.</p>
|
|
<h4><a class="anchor" href="#web-app-request-theme" id="web-app-request-theme" name="web-app-request-theme"><i class="anchor-icon"></i></a><code>web_app_request_theme</code></h4>
|
|
<p>No event payload.</p>
|
|
<p>Used by web apps to request information about the current theme, clients should emit a <a href="/api/bots/webapps#theme-changed">theme_changed event</a>.</p>
|
|
<h4><a class="anchor" href="#web-app-ready" id="web-app-ready" name="web-app-ready"><i class="anchor-icon"></i></a><code>web_app_ready</code></h4>
|
|
<p>No event payload.</p>
|
|
<p>Emitted by web apps when they are fully loaded, signaling to client apps that the loading spinner placeholder can be removed. </p>
|
|
<p>Note that there is no guarantee that this event will be emitted when the web app is fully loaded: clients should remove the loading spinner upon receiving this event or when the page finishes loading (native webview/iframe event), whichever event comes first.</p>
|
|
<h4><a class="anchor" href="#web-app-setup-main-button" id="web-app-setup-main-button" name="web-app-setup-main-button"><i class="anchor-icon"></i></a><code>web_app_setup_main_button</code></h4>
|
|
<p>Event payload: JSON object with the following fields:</p>
|
|
<ul>
|
|
<li><code>is_visible</code> - Whether the main button is visible (boolean, false by default)</li>
|
|
<li><code>is_active</code> - Whether the main button is active (boolean, true by default)</li>
|
|
<li><code>text</code> - Button text (string, if <code>trim(text)</code> is empty the button must be hidden)</li>
|
|
<li><code>color</code> - Button color in hex RGB format (string, defaults to the <a href="/api/bots/webapps#theme-parameters"><code>button_color</code> theme parameter</a>)</li>
|
|
<li><code>text_color</code> - Button text color in hex RGB format (string, defaults to the <a href="/api/bots/webapps#theme-parameters"><code>button_text_color</code> theme parameter</a>)</li>
|
|
<li><code>is_progress_visible</code> - Indicates whether the button should display a loading indicator (boolean, false by default)</li>
|
|
</ul>
|
|
<p>Configures the main button, located immediately below the webview: when the user presses it a <a href="/api/bots/webapps#main-button-pressed"><code>main_button_pressed</code> event should be emitted by the client</a>. </p>
|
|
<p>Some clients implement a horizontal media type tab bar located at the bottom of the screen, opened when the user clicks on the attachment menu button: this tab bar contains a horizontal list of buttons used to attach media of a certain type and to open installed <a href="/api/bots/attach">attachment menu web apps</a>.<br>
|
|
In clients that implements a tab bar, iff the user opens a web app through a tab bar button and the web app emits a <code>web_app_setup_main_button</code> with <code>is_visible=true</code>, the main button should be displayed (replacing the tab bar) only after the first tap inside of the webview, to prevent bots from immediately blocking the tab bar. </p>
|
|
<p>Otherwise, the main button can be displayed right away with no user interaction when receiving a <code>web_app_setup_main_button</code> event with <code>is_visible=true</code>. </p>
|
|
<h4><a class="anchor" href="#web-app-setup-back-button" id="web-app-setup-back-button" name="web-app-setup-back-button"><i class="anchor-icon"></i></a><code>web_app_setup_back_button</code></h4>
|
|
<p>Event data: a JSON object with an <code>is_visible</code> boolean field.</p>
|
|
<p>Determines whether to show or hide the back button: when the user presses it a <a href="/api/bots/webapps#back-button-pressed"><code>back_button_pressed</code> event should be emitted by the client</a>.<br>
|
|
Note that on supported platforms, the OS back button can be used instead of a custom back button: in this case, if <code>is_visible</code> is true pressing the OS back button should emit a <a href="/api/bots/webapps#back-button-pressed"><code>back_button_pressed</code> event</a>, otherwise the webview should be closed.</p>
|
|
<h4><a class="anchor" href="#payment-form-submit" id="payment-form-submit" name="payment-form-submit"><i class="anchor-icon"></i></a><code>payment_form_submit</code></h4>
|
|
<p>Event payload: JSON object with <code>credentials</code> and <code>title</code> fields.</p>
|
|
<ul>
|
|
<li><code>title</code> is the censored credit card title. </li>
|
|
<li><code>credentials</code> is a service-specific JSON object with information about the payment credentials provided by the user to the payment system. </li>
|
|
</ul>
|
|
<p><strong>Neither Telegram, nor bots will have access to your credit card information.</strong><br>
|
|
Credit card details will be handled only by the payment system, see the <a href="/api/payments">payment documentation for more info »</a>. </p>
|
|
<h4><a class="anchor" href="#share-score" id="share-score" name="share-score"><i class="anchor-icon"></i></a><code>share_score</code></h4>
|
|
<p>No event payload.</p>
|
|
<p>Will be called by games when the user explicitly clicks on the <strong>share score</strong> button to share the game, along with their score.<br>
|
|
Typically done by using <a href="/method/messages.forwardMessages">messages.forwardMessages</a> on the game message with the <code>with_my_score</code> flag. </p>
|
|
<h4><a class="anchor" href="#share-game" id="share-game" name="share-game"><i class="anchor-icon"></i></a><code>share_game</code></h4>
|
|
<p>No event payload.</p>
|
|
<p>Will be called by games when the user explicitly clicks on the <strong>share game</strong> button to share the game, without sharing their score.<br>
|
|
Typically done by using <a href="/method/messages.forwardMessages">messages.forwardMessages</a> on the game message without the <code>with_my_score</code> flag, or by sharing the game's <a href="/api/links#game-links">deep link</a>.</p>
|
|
<h4><a class="anchor" href="#game-over" id="game-over" name="game-over"><i class="anchor-icon"></i></a><code>game_over</code></h4>
|
|
<p>No event payload.</p>
|
|
<p>Can be called by games when the user loses a game.</p>
|
|
<h4><a class="anchor" href="#game-loaded" id="game-loaded" name="game-loaded"><i class="anchor-icon"></i></a><code>game_loaded</code></h4>
|
|
<p>No event payload.</p>
|
|
<p>Can be called by games once the game fully loads.</p>
|
|
<h4><a class="anchor" href="#resize-frame" id="resize-frame" name="resize-frame"><i class="anchor-icon"></i></a><code>resize_frame</code></h4>
|
|
<p>Event payload: JSON object with <code>height</code> field.</p>
|
|
<p>Called by supported pages inside of <a href="https://instantview.telegram.org">IV</a> iframe embeds, indicates the new size of the embed frame.</p></div>
|
|
|
|
</div>
|
|
|
|
</div>
|
|
</div>
|
|
<div class="footer_wrap">
|
|
<div class="footer_columns_wrap footer_desktop">
|
|
<div class="footer_column footer_column_telegram">
|
|
<h5>Telegram</h5>
|
|
<div class="footer_telegram_description"></div>
|
|
Telegram is a cloud-based mobile and desktop messaging app with a focus on security and speed.
|
|
</div>
|
|
|
|
<div class="footer_column">
|
|
<h5><a href="//telegram.org/faq">About</a></h5>
|
|
<ul>
|
|
<li><a href="//telegram.org/faq">FAQ</a></li>
|
|
<li><a href="//telegram.org/privacy">Privacy</a></li>
|
|
<li><a href="//telegram.org/press">Press</a></li>
|
|
</ul>
|
|
</div>
|
|
<div class="footer_column">
|
|
<h5><a href="//telegram.org/apps#mobile-apps">Mobile Apps</a></h5>
|
|
<ul>
|
|
<li><a href="//telegram.org/dl/ios">iPhone/iPad</a></li>
|
|
<li><a href="//telegram.org/android">Android</a></li>
|
|
<li><a href="//telegram.org/dl/web">Mobile Web</a></li>
|
|
</ul>
|
|
</div>
|
|
<div class="footer_column">
|
|
<h5><a href="//telegram.org/apps#desktop-apps">Desktop Apps</a></h5>
|
|
<ul>
|
|
<li><a href="//desktop.telegram.org/">PC/Mac/Linux</a></li>
|
|
<li><a href="//macos.telegram.org/">macOS</a></li>
|
|
<li><a href="//telegram.org/dl/web">Web-browser</a></li>
|
|
</ul>
|
|
</div>
|
|
<div class="footer_column footer_column_platform">
|
|
<h5><a href="/">Platform</a></h5>
|
|
<ul>
|
|
<li><a href="/api">API</a></li>
|
|
<li><a href="//translations.telegram.org/">Translations</a></li>
|
|
<li><a href="//instantview.telegram.org/">Instant View</a></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<div class="footer_columns_wrap footer_mobile">
|
|
<div class="footer_column">
|
|
<h5><a href="//telegram.org/faq">About</a></h5>
|
|
</div>
|
|
<div class="footer_column">
|
|
<h5><a href="//telegram.org/blog">Blog</a></h5>
|
|
</div>
|
|
<div class="footer_column">
|
|
<h5><a href="//telegram.org/apps">Apps</a></h5>
|
|
</div>
|
|
<div class="footer_column">
|
|
<h5><a href="/">Platform</a></h5>
|
|
</div>
|
|
<div class="footer_column">
|
|
<h5><a href="https://twitter.com/telegram" target="_blank" data-track="Follow/Twitter" onclick="trackDlClick(this, event)">Twitter</a></h5>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<script src="/js/main.js?47"></script>
|
|
<script src="/js/jquery.min.js?1"></script>
|
|
<script src="/js/bootstrap.min.js?1"></script>
|
|
|
|
<script>window.initDevPageNav&&initDevPageNav();
|
|
backToTopInit("Go up");
|
|
removePreloadInit();
|
|
</script>
|
|
</body>
|
|
</html>
|
|
|