# Connecting a Mini App
To connect a Mini App, you need to add it on the relevant page (Mini Apps).
{% hint style="info" %}
Before adding a Mini App, ensure that you’ve added the bot if you haven’t done so yet. It is not mandatory to connect the bot when adding the Mini App, but for better context, we recommend doing so.
By connecting the bot, you’ll get the maximum amount of information.
{% endhint %}
## Mini App Setup
The system will ask you to choose the bot to which the Mini App belongs and its system name.
{% hint style="warning" %}
The system name is necessary for matching data received by the bot. If you enter an incorrect name, the system will create a Mini App with the name found, which may cause data confusion.
{% endhint %}
## Adding a Counter to the HTML Code of the Mini App
\
After adding the Mini App to graspil, you will receive a key and a code that needs to be added to your Mini App.
Replace the placeholder `<--YOUR CODE-->` in line 5 with the key you received:
{% code overflow="wrap" lineNumbers="true" %}
```javascript
```
{% endcode %}
This code should be added in the `` section of your application.
## Connecting Mini Apps Without the Telegram Object
Some libraries for Telegram Mini Apps remove or clear the global `window.Telegram` object (for example, the [@telegram-apps library](https://docs.telegram-mini-apps.com/)).
To ensure analytics work correctly in such applications, you need to perform the following additional steps:
#### Passing [initData](https://core.telegram.org/bots/webapps#initializing-mini-apps) and Additional Parameters
{% code title="Example Initialization" overflow="wrap" lineNumbers="true" %}
```javascript
window.graspil.push(
{
custom_init_data_row: Telegram.WebApp.initData, // initData as a string
platform: Telegram.WebApp.platform,
version: Telegram.WebApp.version,
viewportHeight: Telegram.WebApp.viewportHeight,
viewportStableHeight: Telegram.WebApp.viewportStableHeight,
colorScheme: Telegram.WebApp.colorScheme
}
)
```
{% endcode %}
*An example of how to retrieve these values using **@telegram-apps** can be found* [*here*](https://github.com/Telegram-Mini-Apps/reactjs-js-template/blob/master/src/pages/InitDataPage.jsx)
#### Manual Tracking of Standard Events
Automatic tracking of standard Mini App events (such as `mainButtonClicked`, `backButtonClicked`, etc.) will not work in this case.
If you want to track such events, you’ll need to send them manually using the event tracking code.
For the `event` and `category` fields, use the event name (e.g., `mainButtonClicked`, etc.).
## Event Tracking
By default, the system collects click events on buttons and links, as well as all events generated by Telegram.
For clicks, the event names are derived from the button and link content. You can pass custom events by adding the data-gs-event attribute to HTML elements.
{% code overflow="wrap" lineNumbers="true" %}
```html
Start
Start
```
{% endcode %}
## Custom Events
You can pass custom events by running the following code:
{% code overflow="wrap" lineNumbers="true" %}
```json
graspil.push(
{
event: 'Event Name',
category: 'Event Category', // optional
value_num: 100, // optional
unit: 'usd' // optional
}
)
```
{% endcode %}
| Parameter | Type | Required | Description |
| ---------- | --------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| event | string | yes | Event name |
| category | string | no | Event category |
| value\_num | float | no | Numerical value, such as price (a floating-point number) |
| unit | string(3) | yes, if value\_num is provided | Currency code, maximum length of 3 characters. Same as in [*TG Api*](https://core.telegram.org/bots/payments#supported-currencies) |
## UTM Tracking
UTM tracking works within the general graspil system, similar to the [tags in the bot](/en/app/start-utm.md). This means that if the user’s [source](/en/app/start-utm/source.md) is identified in the bot, it will be retained (within the [attribution models](/en/app/attribution-models.md)) for the user who launches the Mini App, and vice versa.
**UTM Tag Processing Rules**
The tags are processed according to the rules set in the bot. For more details, [see here.](/en/app/start-utm/configuring-start.md)
**How to Add UTM Tags?**
Tags are added similarly to the ones in the bot, with one exception: instead of using `start`, you need to use the parameter `startapp`.
Example:`https://t.me/graspil_bot/app?startapp=source-doc`
## Tracking Launch Buttons
By default, graspil can identify where the Mini App was launched from—either a public channel/chat or your bot. However, you also have the option to configure tracking for launches from specific buttons.
{% hint style="info" %}
This is not related to UTM tags. These are two separate, independent systems for identifying traffic sources.
{% endhint %}
For example, your bot might offer users three buttons to launch the Mini App:
1. Menu Button (the standard button next to the input field)
2. “Open App” Button on the bot’s page (where the bot description and username are shown)
3. Most likely, you also send a welcome message to users with a button to launch the app
For each of these buttons, you can define an HTTPS address for your app. For instance: `https://example.com/myapp`
If you add the parameter `gs_source=my_button` to this URL, this value will be used as the session source in the Mini App, and you’ll be able to see this data in the corresponding reports.
#### Examples:
\
Using the buttons listed above as examples, we’ll add the gs\_source parameter to each link:
• Menu Button: `https://example.com/myapp?gs_source=menu_button`
• “Open App” Button: `https://example.com/myapp?gs_source=main_button`
• Start Message Button: `https://example.com/myapp?gs_source=start_msg`
{% hint style="info" %}
If your link already has parameters, you can add `gs_source` using an ampersand &:
`https://example.com/myapp?myparam=val&gs_source=menu_button`
{% endhint %}
You can use the `gs_source` parameter anywhere you have a direct link to the app. For all other cases, use UTM tags.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.graspil.com/en/connect-bot/mini-app.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.