Skip to content

Commit aea9e8d

Browse files
heyqbnkheyqbnk
committed
chore: actualize readme
1 parent 354006c commit aea9e8d

File tree

1 file changed

+149
-5
lines changed

1 file changed

+149
-5
lines changed

‎README.md

Lines changed: 149 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,162 @@
11
# init-data-golang
22

3-
Package which provides utilities to work with Telegram Mini Apps init data.
4-
To learn more, what init data is, visit its [documentation](https://docs.telegram-mini-apps.com/platform/init-data).
3+
The package that provides utilities to work with
4+
the [initialization data](https://docs.telegram-mini-apps.com/platform/init-data) of Telegram Mini
5+
Apps.
56

67
## Installation
78

89
```bash
910
go get github.com/telegram-mini-apps/init-data-golang
1011
```
1112

12-
## Documentation
13+
## Validation
1314

14-
You can find full package documentation [here](https://docs.telegram-mini-apps.com/packages/init-data-golang).
15+
If the expiration time is set to `0`, the function will skip the expiration time check. However, it
16+
is recommended to specify a non-zero value, as this check is considered important in preventing the
17+
usage of old stolen initialization data.
18+
19+
```go
20+
package main
21+
22+
import (
23+
"fmt"
24+
"time"
25+
26+
initdata "github.com/telegram-mini-apps/init-data-golang"
27+
)
28+
29+
func main() {
30+
// Init data in raw format.
31+
initData := "user=%7B%22id%22%3A279058397%2C%22first_name%22%3A%22Vladislav%20%2B%20-%20%3F%20%5C%2F%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%2C%22allows_write_to_pm%22%3Atrue%2C%22photo_url%22%3A%22https%3A%5C%2F%5C%2Ft.me%5C%2Fi%5C%2Fuserpic%5C%2F320%5C%2F4FPEE4tmP3ATHa57u6MqTDih13LTOiMoKoLDRG4PnSA.svg%22%7D&chat_instance=8134722200314281151&chat_type=private&auth_date=1733509682&signature=TYJxVcisqbWjtodPepiJ6ghziUL94-KNpG8Pau-X7oNNLNBM72APCpi_RKiUlBvcqo5L-LAxIc3dnTzcZX_PDg&hash=a433d8f9847bd6addcc563bff7cc82c89e97ea0d90c11fe5729cae6796a36d73"
32+
33+
// Telegram Bot secret key.
34+
token := "7342037359:AAHI25ES9xCOMPokpYoz-p8XVrZUdygo2J4"
35+
36+
// Define how long since init data generation date init data is valid.
37+
expIn := 24 * time.Hour
38+
39+
// Will return error in case, init data is invalid.
40+
fmt.Println(initdata.Validate(initData, token, expIn))
41+
}
42+
43+
```
44+
45+
### Third-Party Validation
46+
47+
The package allows validating init data to check if it was signed by Telegram.
48+
49+
To do so, call the `ValidateThirdParty` function with the following arguments:
50+
51+
- `initData: string`: Init data in raw format.
52+
- `botID: int64`: The Telegram Bot issuer identifier for the init data.
53+
- `expIn: time.Time`: The maximum lifetime of the init data.
54+
55+
Here is an example:
56+
57+
```go
58+
package main
59+
60+
import (
61+
"fmt"
62+
"time"
63+
64+
initdata "github.com/telegram-mini-apps/init-data-golang"
65+
)
66+
67+
func main() {
68+
// Init data in raw format.
69+
initData := "user=%7B%22id%22%3A279058397%2C%22first_name%22%3A%22Vladislav%20%2B%20-%20%3F%20%5C%2F%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%2C%22allows_write_to_pm%22%3Atrue%2C%22photo_url%22%3A%22https%3A%5C%2F%5C%2Ft.me%5C%2Fi%5C%2Fuserpic%5C%2F320%5C%2F4FPEE4tmP3ATHa57u6MqTDih13LTOiMoKoLDRG4PnSA.svg%22%7D&chat_instance=8134722200314281151&chat_type=private&auth_date=1733584787&hash=2174df5b000556d044f3f020384e879c8efcab55ddea2ced4eb752e93e7080d6&signature=zL-ucjNyREiHDE8aihFwpfR9aggP2xiAo3NSpfe-p7IbCisNlDKlo7Kb6G4D0Ao2mBrSgEk4maLSdv6MLIlADQ"
70+
71+
// Telegram Bot secret key.
72+
var botID int64 = 7342037359
73+
74+
// Define how long since init data generation date init data is valid.
75+
expIn := 24 * time.Hour
76+
77+
// Will return an error if init data is invalid.
78+
fmt.Println(initdata.ValidateThirdParty(initData, botID, expIn))
79+
}
80+
```
81+
82+
You can also use the `ValidateThirdPartyWithEnv` function with the additional boolean
83+
argument responsible for marking the environment as the testing one.
84+
85+
## Parsing
86+
87+
It is important to note that the `Parse` function does not perform the same checks as the `Validate`
88+
function. Therefore, this function solely parses incoming data without conducting validations for
89+
the hash or expiration time.
90+
91+
```go
92+
package main
93+
94+
import (
95+
"fmt"
96+
97+
initdata "github.com/telegram-mini-apps/init-data-golang"
98+
)
99+
100+
func main() {
101+
// Init data in raw format.
102+
initData := "user=%7B%22id%22%3A279058397%2C%22first_name%22%3A%22Vladislav%20%2B%20-%20%3F%20%5C%2F%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%2C%22allows_write_to_pm%22%3Atrue%2C%22photo_url%22%3A%22https%3A%5C%2F%5C%2Ft.me%5C%2Fi%5C%2Fuserpic%5C%2F320%5C%2F4FPEE4tmP3ATHa57u6MqTDih13LTOiMoKoLDRG4PnSA.svg%22%7D&chat_instance=8134722200314281151&chat_type=private&auth_date=1733509682&signature=TYJxVcisqbWjtodPepiJ6ghziUL94-KNpG8Pau-X7oNNLNBM72APCpi_RKiUlBvcqo5L-LAxIc3dnTzcZX_PDg&hash=a433d8f9847bd6addcc563bff7cc82c89e97ea0d90c11fe5729cae6796a36d73"
103+
104+
// Will return 2 values.
105+
// 1. InitData instance if passed data has a correct format.
106+
// 2. Error in case, something is wrong.
107+
fmt.Println(initdata.Parse(initData))
108+
}
109+
110+
```
111+
112+
## Signing
113+
114+
The functions that sign data remove parameters such as `hash` and `auth_date` since it is assumed
115+
that the `hash` will be returned by the function and the `auth_date` will be set by the function
116+
itself.
117+
118+
```go
119+
package main
120+
121+
import (
122+
"fmt"
123+
"time"
124+
125+
initdata "github.com/telegram-mini-apps/init-data-golang"
126+
)
127+
128+
func main() {
129+
// Init data in raw format.
130+
initData := "user=%7B%22id%22%3A279058397%2C%22first_name%22%3A%22Vladislav%20%2B%20-%20%3F%20%5C%2F%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%2C%22allows_write_to_pm%22%3Atrue%2C%22photo_url%22%3A%22https%3A%5C%2F%5C%2Ft.me%5C%2Fi%5C%2Fuserpic%5C%2F320%5C%2F4FPEE4tmP3ATHa57u6MqTDih13LTOiMoKoLDRG4PnSA.svg%22%7D&chat_instance=8134722200314281151&chat_type=private&auth_date=1733509682&signature=TYJxVcisqbWjtodPepiJ6ghziUL94-KNpG8Pau-X7oNNLNBM72APCpi_RKiUlBvcqo5L-LAxIc3dnTzcZX_PDg&hash=a433d8f9847bd6addcc563bff7cc82c89e97ea0d90c11fe5729cae6796a36d73"
131+
132+
// Telegram Bot secret key.
133+
token := "7342037359:AAHI25ES9xCOMPokpYoz-p8XVrZUdygo2J4"
134+
135+
// Signing timestamp.
136+
// Here we took the value from the initData variable
137+
// above (auth_date query parameter).
138+
authDate := time.Unix(1733509682, 0)
139+
140+
// Signing query parameters.
141+
// Returned values:
142+
// 1. Parameters sign result ("hash" init data property).
143+
// 2. Error occurring while parsing query string as query parameters.
144+
fmt.Println(initdata.SignQueryString(initData, token, authDate))
145+
146+
// Signing the same query parameters presented as a map.
147+
fmt.Println(initdata.Sign(map[string]string{
148+
"user": "{\"id\":279058397,\"first_name\":\"Vladislav + - ? \\/\",\"last_name\":\"Kibenko\",\"username\":\"vdkfrost\",\"language_code\":\"ru\",\"is_premium\":true,\"allows_write_to_pm\":true,\"photo_url\":\"https:\\/\\/t.me\\/i\\/userpic\\/320\\/4FPEE4tmP3ATHa57u6MqTDih13LTOiMoKoLDRG4PnSA.svg\"}",
149+
"chat_instance": "8134722200314281151",
150+
"chat_type": "private",
151+
"signature": "TYJxVcisqbWjtodPepiJ6ghziUL94-KNpG8Pau-X7oNNLNBM72APCpi_RKiUlBvcqo5L-LAxIc3dnTzcZX_PDg",
152+
}, token, authDate))
153+
154+
// In the console, you should see the same results.
155+
}
156+
157+
```
15158

16159
## GoDoc
17160

18-
Package [GoDoc](https://pkg.go.dev/github.com/telegram-mini-apps/init-data-golang).
161+
To see GoDoc documentation,
162+
visit [this link](https://pkg.go.dev/github.com/telegram-mini-apps/init-data-golang).

0 commit comments

Comments
 (0)