search

mobile-screen-buttonConnecting a Mini App

To connect a Mini App, you need to add it on the relevant page (Mini Apps).

circle-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.

hashtag
Mini App Setup

The system will ask you to choose the bot to which the Mini App belongs and its system name.

circle-exclamation

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.

hashtag
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:

<script type="text/javascript">
  (function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({key:i});
    var f=d.getElementsByTagName(s)[0],j=d.createElement(s);
    j.async=true;j.src="https://w.graspil.com";f.parentNode.insertBefore(j,f);
  })(window,document,"script","graspil","<--YOUR CODE-->");
</script>

This code should be added in the <head> section of your application.

hashtag
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 libraryarrow-up-right).

To ensure analytics work correctly in such applications, you need to perform the following additional steps:

hashtag
Passing initDataarrow-up-right and Additional Parameters

An example of how to retrieve these values using @telegram-apps can be found herearrow-up-right

hashtag
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.).

hashtag
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.

hashtag
Custom Events

You can pass custom events by running the following code:

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 Apiarrow-up-right

hashtag
UTM Tracking

UTM tracking works within the general graspil system, similar to the tags in the bot. This means that if the user’s source is identified in the bot, it will be retained (within the attribution models) 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.

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

hashtag
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.

circle-info

This is not related to UTM tags. These are two separate, independent systems for identifying traffic sources.

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.

hashtag
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

circle-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

You can use the gs_source parameter anywhere you have a direct link to the app. For all other cases, use UTM tags.

PreviousOutgoing Data ConnectionNextConnecting the bot on the constructor

Last updated