Telegram 小程序 | Node @telegram-apps/init-data-node

riyad

该软件包提供在 服务器端处理 Telegram 迷你应用程序初始化数据的实用程序。 要了解有关初始化数据及其用法的更多信息，请参阅 the documentation.安装
/ s+ z  g% Z! D) xpnpm :
* f9 g; ]  j  m

1. pnpm i @telegram-apps/init-data-node

复制代码

npm :
( k; Z9 T$ ^2 d# S3 D5 n7 _

1. npm i @telegram-apps/init-data-node

复制代码

yarn :

1. yarn add @telegram-apps/init-data-node

复制代码

解析​

要将一个值解析为 init 数据，请使用 parse 方法。

该方法接受以 string 或 URLSearchParams 形式呈现的 init 数据。

1. import { parse } from '@telegram-apps/init-data-node';
   
2. 
   
3. try {
   # |6 N3 v3 I2 `; k% S- v
4.   const initData = parse('...');
   
5.   // {
   " A8 e8 o1 ?% o3 G
6.   //   canSendAfter: 10000,
   % `3 c5 M$ V, Q2 a' G4 J) L
7.   //   chat: {
   : B8 s0 p( j. r1 ?3 s
8.   //     id: 1,
   
9.   //     type: 'group',
   
10.   //     username: 'my-chat',
    7 \+ @! L: r+ F3 Y! i( n5 n
11.   //     title: 'chat-title',
    5 h& }" E: b; Q: t
12.   //     photoUrl: 'chat-photo',
    " P5 b7 v6 P' |3 K: v
13.   //   },
    
14.   //   chatInstance: '888',
    
15.   //   chatType: 'sender',
    ; x3 u4 `' X0 s1 S" G2 A( ^% b
16.   //   queryId: 'QUERY',
    / j0 E! j) q; p
17.   //   receiver: {
    
18.   //     addedToAttachmentMenu: false,
      W7 a% K# _& c( M: Y
19.   //     allowsWriteToPm: true,
    
20.   //     firstName: 'receiver-first-name',
    3 m: u6 b- m9 A/ G
21.   //     id: 991,
    : U  q* T5 v2 n/ L* b. k
22.   //     isBot: false,
    
23.   //     isPremium: true,
    - }7 p+ U! I# y7 \* \# y' B0 l
24.   //     languageCode: 'ru',
    , i. j+ U, m) ~' ^& P; e) v: b
25.   //     lastName: 'receiver-last-name',
    
26.   //     photoUrl: 'receiver-photo',
    8 ^/ A! C7 H* r7 X
27.   //     username: 'receiver-username',
    
28.   //   },
    - |" C& t2 h$ t, C
29.   //   startParam: 'debug',
    
30.   //   user: {
    ; L8 F7 P9 H; K% f/ o9 y( z
31.   //     addedToAttachmentMenu: false,
    
32.   //     allowsWriteToPm: false,
    
33.   //     firstName: 'user-first-name',
    1 _/ n( p' f' h' C2 p% I
34.   //     id: 222,
    3 `$ ~. q4 Q: G% \- X) [
35.   //     isBot: true,
    ' T/ p6 i, \% Q+ M5 L! ~  _
36.   //     isPremium: false,
    
37.   //     languageCode: 'en',
    
38.   //     lastName: 'user-last-name',
    : x8 s) O; V* b, S
39.   //     photoUrl: 'user-photo',
    * r& ?; R! v& X. g
40.   //     username: 'user-username',
    
41.   //   },
    * A* G1 I9 L8 c# d
42.   // }
    9 ~5 h) G* V/ Q/ x, A! v
43. } catch (e) {
    5 G+ ^. {9 R% |! `  c% I1 s7 A
44.   console.error('Something is wrong', e);
    7 _6 \* `8 W/ R4 `; n  \( h
45. }

复制代码

验证​validate​

要验证初始化数据的签名，需要使用validate函数。 它希望 以原始格式（搜索参数）传递初始化数据，并在 某些情况下出错。

1. import { validate } from '@telegram-apps/init-data-node';
   
2. 
   % S% ]" c# {# s) w5 z2 T
3. const secretToken = '5768337691:AAH5YkoiEuPk8-FZa32hStHTqXiLPtAEhx8';
   
4. const initData =
   
5.   'query_id=AAHdF6IQAAAAAN0XohDhrOrc' +
   
6.   '&user=%7B%22id%22%3A279058397%2C%22first_name%22%3A%22Vladislav%22%2C%22last_name%22%3A%22Kibenko%22%2C%22username%22%3A%22vdkfrost%22%2C%22language_code%22%3A%22ru%22%2C%22is_premium%22%3Atrue%7D' +
   
7.   '&auth_date=1662771648' +
   
8.   '&hash=c501b71e775f74ce10e377dea85a7ea24ecd640b223ea86dfe453e0eaed2e2b2';
   7 V; ]0 {: }/ g3 K
9. 
   
10. validate(initData, secretToken);

复制代码

函数会在其中一种情况下出错：

• ERR_AUTH_DATE_INVALID：auth_date 为空或未找到
• ERR_HASH_INVALID：hash 为空或未找到
• ERR_SIGN_INVALID：签名无效
• ERR_EXPIRED：初始数据已过期
  

以下是您可以用来检查错误类型的代码：

1. import { validate, isErrorOfType } from '@telegram-apps/init-data-node';
   + v7 t7 v; K3 \
2. 
   # X" m& D, r) [+ l+ e0 d
3. try {
   
4.   validate('init-data', 'token');
   - g- n) ^! {2 }) w' T* p
5. } catch (e) {
   ( |2 F& u# \0 K7 f5 t9 g
6.   if (isErrorOfType('ERR_SIGN_INVALID')) {
   . c) Y% k4 s9 @6 f, z# A' y
7.     console.log('Sign is invalid');
   
8.   }
   
9. }

复制代码

默认情况下，函数会检查初始化数据是否过期。 的默认过期时间设置为 1 天（86,400 秒）。 建议始终检查 初始化数据的有效期，因为它可能被盗但仍然有效。 要禁用此功能，将 { expiresIn: 0 } 作为第三个参数。

isValid​

或者，开发人员可以使用 isValid 函数来检查初始数据的有效性。 它不会引发错误，但会返回一个布尔值，表明初始数据的有效性。

1. import { isValid } from '@telegram-apps/init-data-node';
   * G2 T) @, J! g' @/ S2 P- C
2. 
   
3. if (isValid('init-data')) {
   
4.   console.log('Init data is fine');
   
5. }

复制代码

签名​

在某些情况下，开发人员可能需要创建自己的初始数据。 例如，如果您使用 KeyboardButton 或 InlineKeyboardButton， Telegram 不会自动发送这些数据。 Telegram 无法做到这一点，因为它不知道应该使用哪个 Telegram Bot 令牌 。

要实现这一过程，需要使用 sign 方法。 下面是完整的示例：

Signing :

1. import { sign } from '@telegram-apps/init-data-node';
   - D( y: w, S5 R% g& N3 _
2. 
   
3. sign(
   - J4 t& R( |7 M% A0 E2 e
4.   {
   # h8 y  p) ?. B
5.     canSendAfter: 10000,
   / R% {+ e5 R$ p1 K6 F- B2 D
6.     chat: {
   4 x+ E' _; X5 I& ?
7.       id: 1,
   " Y- x* T% C* `/ F6 {  C
8.       type: 'group',
   " l/ [; }4 T1 G0 ~1 c" ~8 y% I
9.       username: 'my-chat',
   ( j0 O" E: x6 K
10.       title: 'chat-title',
    9 ~5 [% x- Q$ M3 B1 Z
11.       photoUrl: 'chat-photo',
    
12.     },
    
13.     chatInstance: '888',
    
14.     chatType: 'sender',
    
15.     queryId: 'QUERY',
    
16.     receiver: {
    
17.       addedToAttachmentMenu: false,
    
18.       allowsWriteToPm: true,
    
19.       firstName: 'receiver-first-name',
    8 T  d$ K$ c0 m) j
20.       id: 991,
    
21.       isBot: false,
    
22.       isPremium: true,
    
23.       languageCode: 'ru',
    
24.       lastName: 'receiver-last-name',
    ' P- E' d) L8 t9 ~" l1 b2 y
25.       photoUrl: 'receiver-photo',
    
26.       username: 'receiver-username',
    ( G9 K. Q' @% u( `6 M0 f+ ]
27.     },
    
28.     startParam: 'debug',
    - L- i9 _# \8 X9 m. y/ u4 e
29.     user: {
    
30.       addedToAttachmentMenu: false,
    , Y' X) z! g0 |/ H  D. h3 l+ c
31.       allowsWriteToPm: false,
    
32.       firstName: 'user-first-name',
    / v: X& ]  o! Y: d3 S
33.       id: 222,
    : U+ ~% v3 @9 W9 B& _
34.       isBot: true,
    2 e" O& U5 k9 u  w; `- J
35.       isPremium: false,
    
36.       languageCode: 'en',
    
37.       lastName: 'user-last-name',
    , M# {/ v/ h! h8 y* A
38.       photoUrl: 'user-photo',
    " W; g4 N" @7 g3 f
39.       username: 'user-username',
    
40.     },
    / z( ~- t4 T* Y8 k
41.   },
    $ g4 [+ _- o' {" }0 |
42.   '5768337691:AAH5YkoiEuPk8-FZa32hStHTqXiLPtAEhx8',
    
43.   new Date(1000),
    
44. );

复制代码

Expected Result :

1. 'auth_date=1' +
   7 j5 d9 b4 E* F( K
2. '&can_send_after=10000' +
   5 J; D$ ~" j# b2 ~( C
3. '&chat=%7B%22id%22%3A1%2C%22type%22%3A%22group%22%2C%22title%22%3A%22chat-title%22%2C%22photo_url%22%3A%22group%22%2C%22username%22%3A%22my-chat%22%7D' +
   
4. '&chat_instance=888' +
   
5. '&chat_type=sender' +
   
6. '&query_id=QUERY' +
   ! N) @+ ?4 j$ _5 v
7. '&receiver=%7B%22added_to_attachment_menu%22%3Afalse%2C%22allows_write_to_pm%22%3Atrue%2C%22first_name%22%3A%22receiver-first-name%22%2C%22id%22%3A991%2C%22is_bot%22%3Afalse%2C%22is_premium%22%3Atrue%2C%22language_code%22%3A%22ru%22%2C%22last_name%22%3A%22receiver-last-name%22%2C%22photo_url%22%3A%22receiver-photo%22%2C%22username%22%3A%22receiver-username%22%7D' +
   6 g2 c9 I; M' [' ~( x7 c
8. '&start_param=debug' +
   3 U2 a- q" w1 l- G: w+ X2 J
9. '&user=%7B%22added_to_attachment_menu%22%3Afalse%2C%22allows_write_to_pm%22%3Afalse%2C%22first_name%22%3A%22user-first-name%22%2C%22id%22%3A222%2C%22is_bot%22%3Atrue%2C%22is_premium%22%3Afalse%2C%22language_code%22%3A%22en%22%2C%22last_name%22%3A%22user-last-name%22%2C%22photo_url%22%3A%22user-photo%22%2C%22username%22%3A%22user-username%22%7D' +
   
10. '&hash=47cfa22e72b887cba90c9cb833c5ea0f599975b6ce7193741844b5c4a4228b40'

复制代码

该函数接受三个参数：

• 要签名的数据：它表示经过解析的初始数据对象，不包括 authDate 和 hash 属性。
• 机器人令牌：该令牌由 [@BotFather] (https://t.me/botfather) 接收。
• 签署日期：此值将用作 authDate 属性的值。
  

因此，函数会返回带符号的 init 数据。

网络加密应用程序接口​

如果要在 Node.js 以外的环境中使用此软件包，开发人员可以使用 web 子目录，该子目录导出的方法与上述方法相同，但会返回承诺。

1. import {
   
2.   validate,
   2 L- w0 n: n9 ^. U% j5 E
3.   sign,
   2 n' S' M9 p! S* l% J2 U! B8 T
4.   signData,
   3 Z7 j' w0 _" |4 D" I  T
5.   isValid,
   
6. } from '@telegram-apps/init-data-node/web';
   
7. 
   
8. await validate(...);
   ' k! _- d( v7 m9 t# c' J
9. await sign(...);
   * ^* d8 `  f0 _+ n* Y  ^
10. await signData(...);
    
11. await isValid(...);

复制代码

传递散列令牌 - Hashed Token​

所有软件包方法都允许开发人员使用散列令牌而不是原始令牌。

我们所说的 "散列令牌 "是指使用 HMAC-SHA-256 算法散列的令牌，其密钥来自 WebAppData，详见 文档的 validation 部分。

下面是一些例子：

1. import { validate, sign } from '@telegram-apps/init-data-node';
   1 R0 i0 w& d4 Q+ }9 F8 A; S
2. 
   
3. const secretTokenHashed = 'a5c609aa52f63cb5e6d8ceb6e4138726ea82bbc36bb786d64482d445ea38ee5f';
   
4. const initData =
   
5.   'query_id=AAHdF6IQAAAAAN0XohDhrOrc' +
   
6.   '&user=%7B%22id%22%3A279058397%2C%22first_name%22%3A%22Vladislav%22%2C%22last_name%22%3A%22Kibenko%22%2C%22username%22%3A%22vdkfrost%22%2C%22language_code%22%3A%22ru%22%2C%22is_premium%22%3Atrue%7D' +
   ' g, m& p6 H2 w  M
7.   '&auth_date=1662771648' +
   0 R" @. z; n6 O. e9 o# ?  }
8.   '&hash=c501b71e775f74ce10e377dea85a7ea24ecd640b223ea86dfe453e0eaed2e2b2';
   
9. 
   7 R0 x1 \" A) V/ e& g+ L3 ^8 E
10. // Validating.
    ( O  i- b9 w  s* k8 C1 {! u0 m1 Q
11. validate(initData, secretTokenHashed, { tokenHashed: true });
    
12. 
    / a( S% t, N0 ^5 V" N  t4 [
13. // Signing.
    ; y, _& P4 [  z' g! g1 k
14. sign(
    
15.   {
    " T' g) @5 J" O! S8 a; }- H
16.     canSendAfter: 10000,
    $ `9 p7 K; y  j5 A$ O
17.     chat: {
    5 _9 D" _$ _' Y' P9 A. J! {
18.       id: 1,
    - v0 y6 ^3 f4 p; C" A1 G
19.       type: 'group',
    
20.       username: 'my-chat',
    
21.       title: 'chat-title',
    $ H9 V, a  h* l3 J, `6 q  i
22.       photoUrl: 'chat-photo',
    
23.     },
    6 v7 V' w' ^- @1 T$ [
24.     chatInstance: '888',
    
25.     chatType: 'sender',
    
26.     queryId: 'QUERY',
    & S( `; E# Q% j, h- S% F2 r
27.     receiver: {
    
28.       addedToAttachmentMenu: false,
    
29.       allowsWriteToPm: true,
    ) P0 X, k+ N9 u3 W4 X
30.       firstName: 'receiver-first-name',
    - Z$ O' ]$ q: t5 G- t1 }. |
31.       id: 991,
    7 s5 c: x& F, ?( g, Z: p* O' V* {( U
32.       isBot: false,
    4 n, g% ~" V6 Y- u
33.       isPremium: true,
    
34.       languageCode: 'ru',
    
35.       lastName: 'receiver-last-name',
    2 l' r2 M/ A+ l; p  G, _( D  S
36.       photoUrl: 'receiver-photo',
    
37.       username: 'receiver-username',
    ! J4 ^1 ?5 _+ a1 {5 e+ ?
38.     },
    ( T" M; Y$ O' X+ m2 b
39.     startParam: 'debug',
    
40.     user: {
    ) p' p. C5 R8 @- t' c% x- R
41.       addedToAttachmentMenu: false,
    # Y& T- R# J& Q
42.       allowsWriteToPm: false,
    
43.       firstName: 'user-first-name',
    
44.       id: 222,
    
45.       isBot: true,
    0 ~' F. c* u, t3 ~
46.       isPremium: false,
    ' V- b8 O4 c  p2 y, v; h4 f+ R
47.       languageCode: 'en',
    
48.       lastName: 'user-last-name',
    ) w' S% c( F9 M" R. c
49.       photoUrl: 'user-photo',
    & |. W9 M. Z9 U6 t
50.       username: 'user-username',
    
51.     },
    ( c5 C7 u) p8 z- {- P" l6 V
52.   },
    " J0 f# T9 j2 ]8 c
53.   secretTokenHashed,
    
54.   new Date(1000),
    
55.   { tokenHashed: true }
    6 s/ D' J1 p. N* @. X
56. );

复制代码

使用这种方法可以减少直接传递原始标记的次数。

, ~7 k8 T4 T! ~) `% M; n! B2 K- ]