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.

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

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

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

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:

  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

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