Connecting a Mini App

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

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.

Mini App Setup

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

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.

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.

Connecting Mini Apps Without the Telegram Object

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

Example Initialization

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
    }
)

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.

<!-- Clicking the element will create an event with the name: -->
<a href="#">Start</a>  <!-- event_name: Start -->
<a href="#" data-gs-event="Game Launch">Start</a>  <!-- event_name: Game Launch -->

Custom Events

You can pass custom events by running the following code:

graspil.push(
    {
        event: 'Event Name',
        category: 'Event Category', // optional
        value_num: 100, // optional
        unit: 'usd' // optional
    }
)

Parameter

Type

Required

Description

event

string

yes

Event name

UTM Tracking

UTM Tag Processing Rules

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.

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:

Menu Button (the standard button next to the input field)
“Open App” Button on the bot’s page (where the bot description and username are shown)
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

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 Connection NextConnecting the bot on the constructor

Last updated 23 days ago

Connecting a Mini App

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

By connecting the bot, you’ll get the maximum amount of information.

Mini App Setup

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

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.

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.

Connecting Mini Apps Without the Telegram Object

Some libraries for Telegram Mini Apps remove or clear the global window.Telegram object (for example, the ).

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

Passing and Additional Parameters

Example Initialization

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
    }
)

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

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.

<!-- Clicking the element will create an event with the name: -->
<a href="#">Start</a>  <!-- event_name: Start -->
<a href="#" data-gs-event="Game Launch">Start</a>  <!-- event_name: Game Launch -->

Custom Events

You can pass custom events by running the following code:

graspil.push(
    {
        event: 'Event Name',
        category: 'Event Category', // optional
        value_num: 100, // optional
        unit: 'usd' // optional
    }
)

Parameter

Type

Required

Description

event

string

yes

Event name

UTM Tracking

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

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

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:

Menu Button (the standard button next to the input field)
“Open App” Button on the bot’s page (where the bot description and username are shown)
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

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 Connection NextConnecting the bot on the constructor

Last updated 23 days ago