JavaScript

Overview

The Dashgram JavaScript SDK is a lightweight analytics library for Telegram Mini Apps built with vanilla JavaScript, TypeScript, or any web framework. It automatically tracks user interactions and sends analytics data to Dashgram.

This SDK is specifically designed for Telegram Mini Apps. It requires your application to be running inside Telegram’s WebApp environment.

Getting Started

1. CDN

Add these scripts to your HTML before the closing </head> tag:

<script src="https://telegram.org/js/telegram-web-app.js"></script>
<script src="https://unpkg.com/@dashgram/javascript@latest/dist/dashgram.min.js"></script>

2. Initialize the SDK

Initialize Dashgram inside </body>:

<script>
  DashgramMini.init({
    projectId: "your-project-id",
    trackLevel: 3
  })
</script>

Required Configuration:

projectId - Your project identifier from the Dashgram dashboard

Optional Configuration:

trackLevel - Event collection level: 1, 2, or 3 (default: 2)
debug - Enable debug logging (default: false)
disabled - Disable all tracking (default: false)
batchSize - Number of events to batch before sending (default: 10)
flushInterval - Milliseconds between automatic flushes (default: 5000)
apiUrl - Custom API endpoint (default: https://api.dashgram.io/v1)
onError - Error callback function

3. Track Custom Events (optional)

If you want to send custom events to Dashgram, use the DashgramMini.track() method. Simply call it with an event name and optional properties whenever the action happens.

DashgramMini.track("purchase_completed", {
  product_id: "premium-plan",
  price: 100,
  currency: "TON"
})

Complete Example

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>My Mini App</title>

    <!-- Telegram WebApp SDK -->
    <script src="https://telegram.org/js/telegram-web-app.js">
    <!-- Telegram Dashgram SDK -->
    <script src="https://unpkg.com/@dashgram/javascript@latest/dist/dashgram.min.js"></script>
  </head>
  <body>
    <h1>My Mini App</h1>
    <button id="purchase-btn">Purchase Premium</button>

    <script>
      // Initialize Dashgram
      DashgramMini.init({
        projectId: "your-project-id",
        trackLevel: 2,
        debug: true // Enable in development
      })

      // Track custom events
      document.getElementById("purchase-btn").addEventListener("click", () => {
        DashgramMini.track("purchase_initiated", {
          product_id: "premium-plan",
          price: 100,
          currency: "TON"
        })
      })
    </script>
  </body>
</html>

Track Levels

Dashgram offers three tracking levels to balance data collection and performance:

Level 1 - Core

Minimal tracking - Basic app lifecycle events only.

Event	Description
`app_open`	Mini App opened or became visible
`app_close`	Mini App closed or hidden

Use when: You only need basic usage metrics.

Level 2 - Interactions (Recommended)

Standard tracking - Level 1 + user interactions.

Event	Description
`screen_view`	Page/route navigation
`button_click`	Button clicks
`link_click`	Link clicks (external detection)
`form_submit`	Form submissions
`input_focus`	Input field focus
`input_change`	Input field value changed
`copy`	Text copied to clipboard
`cut`	Text cut to clipboard
`paste`	Text pasted from clipboard
`text_select`	Text selection
`js_error`	JavaScript errors
`unhandled_rejection`	Unhandled Promise rejections

Use when: You want standard web analytics (recommended for most apps).

Level 3 - Deep Analytics

Comprehensive tracking - Level 1 + 2 + performance metrics + all Telegram events.

Event	Description
`scroll_depth`	Scroll milestone reached
`element_visible`	Tracked element became visible
`rage_click`	Rapid repeated clicks
`long_task`	JS task >50ms
`web_vital_lcp`	Largest Contentful Paint
`web_vital_fid`	First Input Delay
`web_vital_cls`	Cumulative Layout Shift
`network_status`	Online/offline status
`orientation_change`	Device orientation change
`media_play/pause/ended`	Video/audio events
`telegram_theme_changed`	Telegram theme change
`telegram_viewport_changed`	Viewport size change
`telegram_main_button_clicked`	Main button pressed
`telegram_back_button_clicked`	Back button pressed
`telegram_invoice_closed`	Invoice closed
…and all other Telegram events

Use when: You need detailed performance monitoring and all Telegram WebApp events.

TypeScript Support

The SDK includes full TypeScript definitions:

import DashgramMini, { DashgramConfig, EventProperties, TrackLevel } from "@dashgram/javascript"

const config: DashgramConfig = {
  projectId: "your-project-id",
  trackLevel: 2 as TrackLevel
}

DashgramMini.init(config)

const properties: EventProperties = {
  product_id: "premium-plan",
  price: 100
}

DashgramMini.track("purchase_completed", properties)

API Reference

`DashgramMini.init(config)`

Initialize the SDK. Must be called once when your app loads. Parameters:

Parameter	Type	Required	Default	Description
`projectId`	`string`	Yes	—	Your project ID from Dashgram dashboard
`trackLevel`	`1 \| 2 \| 3`	No	`2`	Event collection level
`debug`	`boolean`	No	`false`	Enable debug logging to console
`disabled`	`boolean`	No	`false`	Disable all tracking
`batchSize`	`number`	No	`10`	Number of events to batch before sending
`flushInterval`	`number`	No	`5000`	Milliseconds between automatic flushes
`apiUrl`	`string`	No	`https://api.dashgram.io/v1`	Custom API endpoint
`onError`	`function`	No	—	Callback for handling errors

Example:

DashgramMini.init({
  projectId: "your-project-id",
  trackLevel: 2,
  debug: false,
  batchSize: 20,
  flushInterval: 10000,
  onError: error => {
    console.error("Dashgram error:", error)
  }
})

`DashgramMini.track(event, properties)`

Track a custom event with optional properties. Parameters:

event (string) - Event name
properties (object, optional) - Event properties

Example:

DashgramMini.track("button_clicked", {
  button_name: "purchase",
  product_id: "premium-plan",
  price: 100,
  currency: "TON"
})

`DashgramMini.flush()`

Force send all pending events immediately. Returns a Promise. Use cases:

Before page unload
After critical user actions
When switching users

Example:

// Flush before page unload
window.addEventListener("beforeunload", () => {
  DashgramMini.flush()
})

// Or use async/await
await DashgramMini.flush()

`DashgramMini.shutdown()`

Stop tracking and clean up resources. Useful for:

User opt-out scenarios
App cleanup
Testing

Example:

// User opts out of tracking
DashgramMini.shutdown()

Best Practices

1. Initialize Early

Initialize Dashgram as early as possible in your app lifecycle:

// Good: Initialize immediately
<script>
  DashgramMini.init({ projectId: "your-project-id" })
</script>

// Avoid: Initializing after user interaction
button.addEventListener("click", () => {
  DashgramMini.init({ projectId: "your-project-id" }) // Too late!
})

2. Use Meaningful Event Names

Use clear, descriptive event names:

// Good
DashgramMini.track("purchase_completed", { product_id: "premium" })
DashgramMini.track("user_signed_up", { method: "telegram" })

// Avoid
DashgramMini.track("click", {})
DashgramMini.track("event1", {})

3. Flush Before Unload

Ensure events are sent before the user leaves:

window.addEventListener("beforeunload", () => {
  DashgramMini.flush()
})

4. Handle Errors Gracefully

Use the onError callback to handle errors:

DashgramMini.init({
  projectId: "your-project-id",
  onError: error => {
    // Log to your error tracking service
    console.error("Analytics error:", error)
    // Don't break your app if analytics fails
  }
})

5. Respect User Privacy

Allow users to opt out:

// User opts out
if (userOptedOut) {
  DashgramMini.init({
    projectId: "your-project-id",
    disabled: true
  })
}

Troubleshooting

Events Not Sending

Check initialization: Ensure DashgramMini.init() is called
Verify project ID: Make sure your project ID is correct
Check Telegram environment: SDK only works inside Telegram WebApp
Enable debug mode: Set debug: true to see console logs

DashgramMini.init({
  projectId: "your-project-id",
  debug: true // Check console for logs
})

SDK Not Detecting Telegram

The SDK automatically detects if it’s running in Telegram. If events aren’t being tracked:

Ensure you’re testing inside Telegram (not a regular browser)
Make sure telegram-web-app.js is loaded before Dashgram SDK
Check that Telegram WebApp API is available: window.Telegram?.WebApp

Next Steps

Learn about Track Levels to choose the right level for your app
Check out the React SDK if you’re using React
View your analytics in the Dashgram Dashboard

Getting started

Telegram Bots

Telegram Mini Apps

What's new

Troubleshooting

Overview

Getting Started

1. CDN

2. Initialize the SDK

3. Track Custom Events (optional)

Complete Example

Track Levels

Level 1 - Core

Level 2 - Interactions (Recommended)

Level 3 - Deep Analytics

TypeScript Support

API Reference

`DashgramMini.init(config)`

`DashgramMini.track(event, properties)`

`DashgramMini.flush()`

`DashgramMini.shutdown()`

Best Practices

1. Initialize Early

2. Use Meaningful Event Names

3. Flush Before Unload

4. Handle Errors Gracefully

5. Respect User Privacy

Troubleshooting

Events Not Sending

SDK Not Detecting Telegram

Next Steps

Getting started

Telegram Bots

Telegram Mini Apps

What's new

Troubleshooting

​Overview

​Getting Started

​1. CDN

​2. Initialize the SDK

​3. Track Custom Events (optional)

​Complete Example

​Track Levels

​Level 1 - Core

​Level 2 - Interactions (Recommended)

​Level 3 - Deep Analytics

​TypeScript Support

​API Reference

​DashgramMini.init(config)

​DashgramMini.track(event, properties)

​DashgramMini.flush()

​DashgramMini.shutdown()

​Best Practices

​1. Initialize Early

​2. Use Meaningful Event Names

​3. Flush Before Unload

​4. Handle Errors Gracefully

​5. Respect User Privacy

​Troubleshooting

​Events Not Sending

​SDK Not Detecting Telegram

​Next Steps

Overview

Getting Started

1. CDN

2. Initialize the SDK

3. Track Custom Events (optional)

Complete Example

Track Levels

Level 1 - Core

Level 2 - Interactions (Recommended)

Level 3 - Deep Analytics

TypeScript Support

API Reference

`DashgramMini.init(config)`

`DashgramMini.track(event, properties)`

`DashgramMini.flush()`

`DashgramMini.shutdown()`

Best Practices

1. Initialize Early

2. Use Meaningful Event Names

3. Flush Before Unload

4. Handle Errors Gracefully

5. Respect User Privacy

Troubleshooting

Events Not Sending

SDK Not Detecting Telegram

Next Steps