Connecting Mini App

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

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.

Connecting a Mini App

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

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.

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

<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?l="+l;f.parentNode.insertBefore(j,f);
  })(window,document,"script","graspil","<--YOUR CODE-->");
</script>

This code needs to be added to the <head> section of your application.

Additional settings

You can pass several additional settings during initialization.

Variable

Value

Description

trackClicks

false, tagged

This 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

trackTgEvents

false,true

Determines whether events are automatically created on Mini App service events

Disabling automatic event creation lets you reduce the number of events in the system and therefore optimize service costs

Example code with settings

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

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:

<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?l="+l;f.parentNode.insertBefore(j,f);
  })(window,document,"script","myQueueName","<--YOUR CODE-->");
</script>

Here "graspil" was replaced with "myQueueName". After that, replace all graspil.push(...) calls with myQueueName.push(...).

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.

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 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 object and additional parameters

Initialization example

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 get this data in @telegram-apps is available at https://github.com/Telegram-Mini-Apps/reactjs-js-template/blob/master/src/pages/InitDataPage.jsx

Automatic tracking of standard events (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.

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

You can disable automatic event creation to reduce their number.

Example:

<!-- clicking the element will create an event named: --->
<a href="#">Start</a>  <!--event_name: Start -->
<a href="#" data-gs-event="Launch game">Start</a>  <!--event_name: Launch game -->

Custom events

You can pass your own events by calling

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 tag tracking

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

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.

This is not related to UTM tags. These are two separate, independent systems for determining the traffic source.

For example, your bot provides the user with 3 buttons to launch the Mini App:

The menu button (the standard button next to the input field)
The "Open App" button on the bot's page (where the bot's description and username are)
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:

Menu button - https://example.com/myapp?gs_source=menu_button
"Open App" button - https://example.com/myapp?gs_source=main_button
Button in the start message - https://example.com/myapp?gs_source=start_msg

If your link already uses parameters, you can add gs_source via an ampersand & https://example.com/myapp?myparam=val&gs_source=menu_button

You can use the gs_source parameter anywhere a direct link to the App is used; in other cases, use UTM tags.

PreviousConnecting outbound data

NextConnecting a bot built with a no-code builder

Last updated 26 days ago

Connecting a Mini App

Adding the tracking snippet to your Mini App's HTML code

Additional settings

Example code with settings

Renaming the global variable (if window.graspil is already taken)

Connecting Mini Apps that don't have a Telegram object

Event tracking

Custom events

UTM tag tracking

Tag processing rules

How do I add tags?

Launch button tracking

Examples:

Renaming the global variable (if `window.graspil` is already taken)