> For the complete documentation index, see [llms.txt](https://docs.graspil.com/en/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.graspil.com/en/connect-bot/mini-app.md). # Connecting Mini App To connect a Mini App, you need to add it on the corresponding page ([Mini Apps](https://app.graspil.com/webapps)). {% hint style="info" %} Before adding a Mini App, add the bot if you haven't already. You don't have to connect the bot itself to connect a Mini App, but for a complete picture we recommend doing so.\ By connecting the bot, you'll get the most complete information. {% endhint %} ## Connecting a Mini App The system will ask you to select the bot the Mini App belongs to and its system name. {% hint style="warning" %} The system name is used to match data coming from the bot itself. If you specify the wrong name, when such data is detected the system will create a Mini App with the name found, which will cause confusion in the data. {% endhint %} ## Adding the tracking snippet to your Mini App's HTML code After adding a Mini App to graspil, you'll receive a `key` and code that needs to be added to your Mini App *Replace* `<--YOUR CODE-->` *on line 5 with the* `key` *you received* {% code overflow="wrap" lineNumbers="true" %} ```javascript ``` {% endcode %} This code needs to be added to the \ section of your application. #### Additional settings You can pass several additional settings during initialization.
VariableValueDescription
trackClicksfalse, taggedThis setting determines whether events are automatically created on clicks, true by default.

false - events won't be created automatically
tagged - events will only be created if data-gs-event is specified
trackTgEventsfalse,trueDetermines whether events are automatically created on Mini App service events
{% hint style="info" %} **Disabling automatic event creation** **lets you** reduce the number of events in the system and therefore **optimize service costs** {% endhint %} #### Example code with settings ```javascript ``` ## Renaming the global variable (if `window.graspil` is already taken) By default the script works through the global variable `window.graspil`. If that name is already used by another script in your Mini App, you can rename it — the fourth argument of the snippet call controls this: ```javascript ``` Here `"graspil"` was replaced with `"myQueueName"`. After that, replace all `graspil.push(...)` calls with `myQueueName.push(...)`. {% hint style="warning" %} Don't remove the `?l="+l` part in the `j.src` line — that's how the script learns which name you chose. Without it, the script keeps using `window.graspil` even if you changed the fourth argument. {% endhint %} ### Connecting Mini Apps that don't have a Telegram object Some Telegram Mini App libraries remove or clear the global `window.Telegram` object (for example, the [@telegram-apps](https://docs.telegram-mini-apps.com/) library). For analytics to work correctly in such apps, you need to perform the following additional steps: When the user launches the Mini App, your application should pass the [initData](https://core.telegram.org/bots/webapps#initializing-mini-apps) object and additional parameters {% code title="Initialization example" 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 get this data in* [*@telegram-apps*](https://docs.telegram-mini-apps.com/) *is available at* [*https://github.com/Telegram-Mini-Apps/reactjs-js-template/blob/master/src/pages/InitDataPage.jsx*](https://github.com/Telegram-Mini-Apps/reactjs-js-template/blob/master/src/pages/InitDataPage.jsx) Automatic tracking of [standard events](https://core.telegram.org/bots/webapps#events-available-for-mini-apps) (such as `mainButtonClicked`, `backButtonClicked`, etc.) in the Mini App won't work in this case. If you want to pass such events, you'll need to pass them manually, using the code for [event tracking](#treking-sobytii). For the `event` and `category` field values, use the event name (i.e., for example, `mainButtonClicked`, etc.) ## Event tracking By default, the system collects events for clicks on buttons and links, as well as all events generated by Telegram. For clicks, the contents of the buttons and links are used as event names. You can pass your own events by adding the `data-gs-event` attribute to HTML elements {% hint style="info" %} You can [disable](#dop.-nastroiki) automatic event creation to reduce their number. {% endhint %} **Example:** {% code overflow="wrap" lineNumbers="true" %} ```html Start Start ``` {% endcode %} ### Custom events You can pass your own events by calling {% code overflow="wrap" lineNumbers="true" %} ```javascript graspil.push( { event: 'Event name', category: 'Event category', // optional value_num: 100, // optional unit: 'usd' // optional } ) ``` {% endcode %}
ParameterTypeRequiredDescription
eventstringyesEvent name
categorystringnoCategory name
value_numfloatnoNumeric value, e.g. price (floating-point number).
unitstring(3)yes, if value is presentCurrency code, max string length 3. Similar to currencies in the TG API
## UTM tag tracking UTM tracking works within graspil's general system, similar to [tags in the bot](/en/app/start-utm.md). This means that if a user's [source](/en/app/start-utm/source.md) was determined in the bot, it will be retained (within [attribution models](/en/app/attribution-models.md)) for the user who launched the Mini App, and vice versa. #### Tag processing rules Tags are processed according to the rules set for the bot, [more details here](/en/app/start-utm/configuring-start.md) #### How do I add tags? Tags are added similarly to tags in the bot, with one exception — instead of `start` you need to use the `startapp` parameter Example: `https://t.me/graspil_bot/app?startapp=source-doc` ## Launch button tracking By default, graspil can determine where a Mini App launch came from — a public channel/chat or your bot. But beyond that, you also have the ability to set up tracking for launches from a specific button. {% hint style="info" %} This is not related to UTM tags. These are two separate, independent systems for determining the traffic source. {% endhint %} For example, your bot provides the user with 3 buttons to launch the Mini App: 1. The menu button (the standard button next to the input field) 2. The "Open App" button on the bot's page (where the bot's description and username are) 3. And most likely you send the user a start message with an App launch button For each such button, you set the https address of your application, for example: `https://example.com/myapp`. If you add the `gs_source=my_button` parameter to this address, that 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:** As examples, let's take the buttons listed above and add the `gs_source` parameter to each link: 1. Menu button - `https://example.com/myapp?gs_source=menu_button` 2. "Open App" button - `https://example.com/myapp?gs_source=main_button` 3. Button in the start message - `https://example.com/myapp?gs_source=start_msg` {% hint style="info" %} If your link already uses parameters, you can add `gs_source` via an ampersand **&** `https://example.com/myapp?myparam=val&gs_source=menu_button` {% endhint %} You can use the `gs_source` parameter anywhere a direct link to the App is used; in other cases, use UTM tags.