웹_app타입키보드 버튼에서 시작된TL;DR:웹 앱은텔레그램으로서비스 메시지에서 bot에 데이터를 다시 보낼 수 있다.WebApp.sendData.이를 통해 봇이 외부 서버와 통신하지 않고도 응답을 만들 수 있다.
사용자들은 사용자지정 키보드, 봇메시지 아래의 버튼을사용하여 봇과 상호작용할 수 있으며, 텔레그램이 지원하는 자유형문자 메시지나첨부파일 형식(사진과 비디오, 파일, 위치, 연락처, 여론 조사)을 통해 봇과 상호작용할 수 있다.훨씬 더 많은 유연성을 위해, 봇은HTML5의 모든 힘을 활용하여 사용자에게 친숙한 입력 인터페이스를 만들 수 있다.
사용자로부터 봇으로 데이터를 다시 전송하기 위해, 웹 앱은텔레그램에 전화를 걸 수 있다.WebApp.sendData메서드.데이터는 서비스 메시지에서 문자열로 봇에 전송된다.봇은 수신 후 사용자와 계속 통신할 수 있다.
좋은 방법:
сustomdata inputinterface(날짜 선택을 위한 개인화된 캘린더, 고급 검색 옵션이 있는 목록에서 데이터 선택, 사용자가 "휠을 돌리고" 사용 가능한 옵션 중 하나를 선택할 수 있는 랜덤라이저 등)
특정 봇에 의존하지 않는재사용가능한구성요소.
인라인 버튼 웹 앱
TL;DR:@DurgerKingBot과 같은 대화형 웹 앱의 경우 기본 사용자정보를 얻고 사용자를 대신하여 봇과의 채팅에 메시지를 보내는 데 사용할 수 있는 웹_app 유형인라인키보드버튼을 사용하십시오.
텍스트 데이터만 수신하는 것이 부족하거나 좀 더 고급스럽고 개인화된 인터페이스가 필요한 경우web_app타입의 인라인키보드버튼을 사용하여 웹 앱을 열 수 있다.
버튼에서, 웹 앱은 버튼에 지정된 URL로 열릴 것이다.사용자의테마 설정외에도 기본 사용자 정보(User Information)를 수신한다.ID,name,username,language_code) 및 세션의 고유 식별자인query_id. 이 식별자는 사용자를 대신하여 bot로 메시지를 다시 보낼 수 있다.
봇은 봇 API 메서드에응답WebAppQuery를 호출하여 사용자가 보낸 인라인 메시지를 bot로 다시 전송하고 웹 앱을 닫을 수 있다.메시지를 받은 후, 봇은 사용자와 계속 통신할 수 있다.
좋은 방법:
완전한 웹 서비스와 모든 종류의 통합.
사용 사례는 사실상무제한이다.
메뉴 단추에서 웹 앱 시작
TL;DR:웹 앱은 사용자 정의된 메뉴 버튼에서 실행할 수 있다.이것은 단순히 앱에 더 빨리 접속할 수 있는 방법을 제공하며,그렇지 않으면인라인버튼에서웹앱을 시작하는 것과동일하다.
기본적으로 봇과의 채팅은 항상 나열된 모든명령에 빠르게 액세스할 수 있는편리한 메뉴버튼을 보여준다.Bot API 6.0으로 이 버튼을사용하여 대신 웹앱을 실행할 수 있다.
메뉴 버튼을 구성하려면 메뉴 버튼이 표시할 텍스트와 웹 앱 URL을 지정해야 한다.이러한 파라미터를 설정하는 방법에는 다음 두 가지가 있다.
모든 사용자에 대해 단추를 사용자 정의하려면@BotFather(다음)를 사용하십시오./setmenubutton명령 또는Bot Settings>메뉴 버튼).
모든 사용자와특정 사용자모두에 대해 단추를 사용자 정의하려면 Bot API에서setChatMenuButton방법을 사용하십시오.예를 들어, 사용자의 언어에 따라 단추 텍스트를 변경하거나 봇의 사용자 설정에 따라 다른 웹 앱에 대한 링크를 표시하십시오.
이와 별도로 메뉴 버튼을 통해 오픈한 웹 앱은인라인 버튼을 사용할 때와똑같은방식으로 작동한다.
봇에 이 기능을 사용하려면테스트 서버의 계정에서@BotFather를 열고/setattach명령 – 또는Bot Settings>Configure Attachment 메뉴로 이동하십시오.그런 다음 첨부파일 메뉴의 아이콘을 통해 봇의 웹 앱을 실행하기 위해 열 URL을 지정하십시오.
봇은 사용자의테마 설정외에 기본 사용자 정보(bot)를 받는다.ID,name,username,language_code,photo), 채팅 파트너에 대한 공개 정보(ID,name,username,photo봇을 연 사용자를 대신하여 모든 유형의 메시지를 채팅으로 보낼 수 있는 웹 보기 세션query_id의 고유 식별자.
봇은 봇 API 메서드가응답하는 웹앱쿼리를 호출할 수 있는데, 봇을 통해 사용자가 인라인 메시지를 시작한 개인 채팅으로 보내고 웹앱을 닫는다.
웹 앱이 사용 가능한 최대 높이로 확장된 경우True.False, 웹 앱이 화면의 일부를 차지하고 확장() 방법을 사용하여 전체 높이로 확장할 수 있는 경우.
뷰포트높이
플로트
웹 앱에서 볼 수 있는 영역의 현재 높이.CSS에서 변수로도 사용 가능var(--tg-viewport-height).
이 애플리케이션은 웹 앱의 상단 부분만 표시할 수 있으며 하단 부분은 화면 영역 밖에 남아 있다.이 위치에서 사용자는 웹 앱을 최대 높이까지 "끌어 당길 수 있고, 봇은expansion()방식을 호출하여 같은 작업을 할 수 있다.웹 앱의 위치가 변경됨에 따라 보이는 영역의 현재 높이 값이 실시간으로 업데이트된다.
이 값의 새로 고침 속도는 창의 아래쪽 테두리를 원활하게 따르기에 충분하지 않다는 점에 유의하십시오.인터페이스 요소를 가시 영역 하단에 고정하는 데 사용해서는 안 된다.그 가치를 이용하는 것이 더 적절하다.viewportStableHeight이 목적으로 야전하다
뷰포트스테이블높이
플로트
웹 앱의 마지막 안정적인 상태에서 보이는 영역의 높이.CSS에서 변수로도 사용 가능var(--tg-viewport-stable-height).
이 애플리케이션은 웹 앱의 상단 부분만 표시할 수 있으며 하단 부분은 화면 영역 밖에 남아 있다.이 위치에서 사용자는 웹 앱을 최대 높이까지 "끌어 당길 수 있고, 봇은expansion()방식을 호출하여 같은 작업을 할 수 있다.의 가치와는 달리viewportHeight, 값viewportStableHeight사용자 제스처 또는 애니메이션 중에 웹 앱의 위치가 변경될 때 변경되지 않음.의 가치viewportStableHeight모든 제스처와 애니메이션이 완성되고 웹 앱이 최종 크기에 도달한 후에 업데이트될 것이다.
이벤트기록viewportChanged매개 변수를 전달하여isStateStable=true이 기능을 사용하면 가시 영역의 높이에 대한 안정적인 상태가 변경될 때 추적할 수 있다.
텔레그램 앱에 웹 앱이 표시될 준비가 되었음을 알리는 방법. 이 방법은 모든 필수 인터페이스 요소가 로드되는 대로 가능한 한 빨리 호출하는 것이 좋다.이 방법을 호출하면 로딩 자리 표시자가 숨겨지고 웹 앱이 표시된다. 메서드를 호출하지 않으면 페이지가 완전히 로드된 경우에만 자리 표시자가 숨겨진다.
팽창시키다
함수
웹 앱을 사용 가능한 최대 높이로 확장하는 방법.웹 앱이 최대 높이로 확장되었는지 확인하려면텔레그램값을 참조하십시오.WebApp.isExpanded매개 변수
클로즈업된
함수
웹 앱을 닫는 방법.
테마파람스
웹앱은 텔레그램 사용자의 앱에 맞춰 실시간으로 인터페이스의외관을 조정할 수 있다.이 개체에는 사용자의 현재 테마 설정이 포함되어 있으며,
밭유형설명
bg_color
끈
선택사항.의 배경색#RRGGBB형식을 갖추다 CSS 변수로도 사용 가능var(--tg-theme-bg-color).
text_color
끈
선택사항.의 기본 텍스트 색상#RRGGBB형식을 갖추다 CSS 변수로도 사용 가능var(--tg-theme-text-color).
힌트_색깔
끈
선택사항.힌트 텍스트 색:#RRGGBB형식을 갖추다 CSS 변수로도 사용 가능var(--tg-theme-hint-color).
link_color
끈
선택사항.링크 색상:#RRGGBB형식을 갖추다 CSS 변수로도 사용 가능var(--tg-theme-link-color).
button_color
끈
선택사항.단추 색상:#RRGGBB형식을 갖추다 CSS 변수로도 사용 가능var(--tg-theme-button-color).
button_text_color
끈
선택사항.단추 텍스트 색#RRGGBB형식을 갖추다 CSS 변수로도 사용 가능var(--tg-theme-button-text-color).
메인버튼
이 물체는 텔레그램 인터페이스의 웹 앱 하단에 표시되는 메인 버튼을 제어한다.
밭유형설명
문자 메시지를 보내다
끈
현재 단추 텍스트.기본적으로계속으로 설정하십시오.
색을 칠하다
끈
현재 단추 색상.로 설정themeParams.button_color결석하여
텍스트 색
끈
현재 단추 텍스트 색상.로 설정themeParams.button_text_color결석하여
볼 수 있는
부울
버튼이 표시되는지 여부를 표시한다.기본적으로false로 설정하십시오.
isActive
부울
버튼이 활성 상태인지 여부를 표시한다.기본적으로true로 설정하십시오.
isProgressVisible
부울
읽기 전용.버튼이 로드 표시기를 표시하는지 여부를 표시한다.
setText(텍스트)
함수
버튼 텍스트를 설정하는 방법.
On클릭(콜백)
함수
누름 이벤트 핸들러 버튼을 설정하는 방법.에 대한 별칭Telegram.WebApp.onEvent('mainButtonClicked', callback)
쇼윈도
함수
버튼을 볼 수 있게 하는 방법. 첨부파일 메뉴에서 웹 앱을 열면 사용자가 웹 앱 인터페이스와 상호 작용할 때까지 기본 단추가 숨겨진다는 점에 유의하십시오.
숨다
함수
버튼을 숨기는 방법.
활성화하다
함수
버튼을 활성화하는 방법.
불능화하다
함수
버튼을 비활성화하는 방법.
showProgress(활성 상태로 leaveActive)
함수
버튼에 로드 표시기를 표시하는 방법. 버튼에 연결된 동작에 시간이 오래 걸릴 수 있는 경우 로딩 진행률을 표시하는 것이 좋다.기본적으로 이 버튼은 작업이 진행 중일 때 비활성화된다.매개 변수인 경우leaveActive=true버튼이 활성화 상태로 유지됨.
hideProgress()
함수
로드 표시기를 숨기는 방법.
setParams(파람)
함수
버튼 파라미터를 설정하는 방법.매개변수 매개 변수는 변경해야 하는 하나 이상의 필드를 포함하는 개체: 텍스트- 버튼 텍스트; color- 버튼 색상; text_color- 버튼 텍스트 색상; is_active- 버튼 활성화; is_light- 버튼을 표시하십시오.
이 모든 방법은 체인으로 연결될 수 있도록 메인버튼 객체를 반환한다.
WebAppInitData
이 개체에는 웹 앱이 열리면 전송되는 데이터가 들어 있다.키보드 버튼에서 웹 앱이 실행된 경우 비어 있다.
밭유형설명
query_id
끈
선택 사항.응답WebAppQuery방법을 통해 메시지를 전송하는 데 필요한 웹 앱 세션의 고유 식별자.
사용자 또는 봇의 고유 식별자.이 숫자는 32개 이상의 유의 비트를 가질 수 있으며 일부 프로그래밍 언어는 이를 해석하는 데 어려움/침묵적인 결함을 가질 수 있다.최대 52개의 유의 비트를 가지고 있으므로, 64비트 정수나 이중 정밀한 플로트 타입은 이 식별자를 저장하기에 안전하다.
선택사항.사용자 프로필 사진의 URL.사진은 .jpeg 또는 .svg 형식일 수 있다.첨부 파일 메뉴에서 실행된 웹 앱에 대해서만 반환됨.
웹 앱을 통해 수신된 데이터의 유효성을 확인하는 중
웹앱을 통해 수신한 데이터를 검증하려면텔레그램에서 데이터를 전송해야 한다.WebApp.init데이터필드의 bot 백엔드.데이터는 일련의 필드 값 쌍으로 구성된 쿼리 문자열이다.
수신된해시매개 변수와 데이터체크문자열의HMAC-SHA-256시그니처 16진수 표현, 비밀 키, 즉봇토큰의HMAC-SHA-256시그니처와 상수 문자열의 HMAC-SHA-256 시그니처를 비교하여 수신된 데이터의 무결성을 확인할 수 있다.WebAppData열쇠로 쓰였다.
데이터 확인 문자열(Data-check-string)은 수신된 모든 필드의 체인으로, 알파벳순으로 정렬되어 있다.key=<value>구분 기호로 사용되는라인 피드문자('\n', 0x0A) 포함 - 예:'auth_date=<auth_date>\nuser=<user>\nquery_id=<query_id>'.
전체 점검은 다음과 같이 보일 수 있다.
data_check_string = ...
secret_key = HMAC_SHA256(<bot_token>, "WebAppData")
if (hex(HMAC_SHA256(data_check_string, secret_key)) == hash) {
// data is from Telegram
}
오래된 데이터의 사용을 방지하려면 웹 앱에서 데이터를 받은 시간의 Unix 타임스탬프가 포함된auth_date필드를 추가로 확인하십시오.
검증되면 서버에서 데이터를 사용할 수 있다.복잡한 데이터 유형은 JSON 직렬화된 개체로 표현된다.
웹 앱에 사용 가능한 이벤트
웹 앱은 텔레그램 앱에서 이벤트를 수신할 수 있으며, 이 앱에 핸들러를 첨부할 수 있다.Telegram.WebApp.onEvent(eventType, eventHandler)방법의내부eventHandler이물체는텔레그램에 관한 것이다.WebApp, 처리기로 전송되는 매개 변수 집합은 이벤트 유형에 따라 달라진다.다음은 가능한 이벤트 목록이다.
eventType설명
themeChanged
사용자의 텔레그램 앱(야간 모드로 전환 포함)에서 테마 설정이 변경될 때마다 발생한다. eventHandler는 매개변수를 수신하지 않으며,이를 통해 새로운 테마 설정 및 색상표를 수신할 수 있다.테마파람과이것.colorScheme.
viewportChanged
웹 앱의 볼 수 있는 섹션이 변경될 때 발생한다. eventHandler는 단일 필드가stateStable인 객체를 수신한다.만약isStateStable= true, 웹 앱의 크기 조정이 완료됨.거짓일 경우 크기 조정은 계속된다(사용자가 웹 앱을 확장하거나 축소하거나 애니메이션 오브젝트가 재생 중).이 뷰포트에서 볼 수 있는 섹션 높이의 현재 값을 사용할 수 있음키.
링크를 열면 사용자에게 봇을 첨부 메뉴에 추가하라는 메시지가 표시된다.봇이 이미 추가된 경우 첨부파일 메뉴는 현재 채팅에서 열리며 그곳의 봇으로 리디렉션된다(1대1 채팅에서 링크를 연 경우).링크에 비어 있지 않은startattach매개변수가 포함된 경우,start_param필드와 GET 매개변수tgWebAppStartParam에서 웹 앱으로 전달된다.
이러한 링크는 특정 사용자와의 채팅의 첨부파일 메뉴에서 웹 앱을 연다.봇이 첨부파일에 아직 추가되지 않은 경우, 사용자에게 첨부파일에 추가하라는 메시지가 나타날 것이다.링크에 비어 있지 않은startattach매개변수가 포함된 경우,start_param필드와 GET 매개변수tgWebAppStartParam에서 웹 앱으로 전달된다.
