@dashgram/react 1.0.1

package/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2024 Dashgram
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+
+
+

package/README.md

@@ -0,0 +1,188 @@
+# Dashgram React SDK
+
+React SDK for **Telegram Mini Apps**. Track user interactions and send events to Dashgram analytics.
+
+> [!NOTE]
+> This SDK is for **Telegram Mini Apps** built with React. For vanilla JavaScript or other frameworks, see our [other SDKs](https://docs.dashgram.io/sdk).
+
+## Quick Start
+
+### 1. Installation
+
+```bash
+npm install @dashgram/react
+# or
+pnpm add @dashgram/react
+# or
+yarn add @dashgram/react
+```
+
+### 2. Basic Setup
+
+Wrap your app with `DashgramProvider`:
+
+```tsx
+import { DashgramProvider } from "@dashgram/react"
+
+export function App() {
+  return (
+    <DashgramProvider projectId="your-project-id" trackLevel={2}>
+      ...
+    </DashgramProvider>
+  )
+}
+```
+
+**Configuration:**
+
+- `projectId` — Your project identifier from the [Dashgram dashboard](https://app.dashgram.io). Get it after creating a project.
+- `trackLevel` — Controls which events are automatically captured. See [Track Levels](#track-levels) section below for details.
+
+### 3. Track custom events (optional)
+
+If you want to send custom events to Dashgram, use the useTrackEvent hook.
+Simply call it with an event name and optional properties whenever the action happens.
+
+```tsx
+import { useTrackEvent } from "@dashgram/react"
+
+export function Button() {
+  const track = useTrackEvent()
+
+  const handleClick = () => {
+    track("button_click", { label: "Buy" })
+  }
+
+  return <button onClick={handleClick}>Click me</button>
+}
+```
+
+## Track Levels
+
+Choose how much data to collect. Higher levels capture more events but send more data.
+
+### 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
+
+**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.
+
+## API Reference
+
+### `<DashgramProvider>`
+
+Provider component that initializes the SDK.
+
+```tsx
+<DashgramProvider projectId="your-project-id" trackLevel={2} debug={false} disabled={false}>
+  <YourApp />
+</DashgramProvider>
+```
+
+**Props:**
+
+- `projectId` — **Required.** Your project ID from [Dashgram dashboard](https://app.dashgram.io)
+- `trackLevel` — Event collection level: `1`, `2`, or `3` (default: `2`)
+- `debug` — Enable debug logging (default: `false`)
+- `disabled` — Disable all tracking (default: `false`)
+
+### `useTrackEvent()`
+
+Hook that returns a function to track custom events with optional properties.
+
+```tsx
+const track = useTrackEvent()
+
+track("purchase_completed", {
+  product_id: "premium-plan",
+  price: 100,
+  currency: "TON"
+})
+```
+
+**Parameters:**
+
+- `event` — Event name (string)
+- `properties` — Optional event properties (object)
+
+### `useDashgram()`
+
+Hook to access the SDK instance.
+
+```tsx
+const { track, isInitialized, flush } = useDashgram()
+
+track("event_name")
+await flush()
+```
+
+### `usePageView(pageName, properties?)`
+
+Track page views for SPA routing.
+
+```tsx
+usePageView("home_page", { section: "landing" })
+```
+
+## Contributing
+
+Contributions are welcome! Please open issues or pull requests on the [GitHub repository](https://github.com/dashgram/dashgram-javascript).
+
+## License
+
+This project is licensed under the MIT License. See the LICENSE file for more information.
+
+## Contact
+
+For questions or support, reach out to us at [team@dashgram.io](mailto:team@dashgram.io) or visit our [website](https://dashgram.io).

package/dist/hooks.d.ts

@@ -0,0 +1,12 @@
+import type { FormEvent } from "react";
+import type { DashgramContextValue } from "./types";
+export declare function useDashgram(): DashgramContextValue;
+export declare function useTrackMount(event: string, properties?: Record<string, any>): void;
+export declare function useTrackUnmount(event: string, properties?: Record<string, any>): void;
+export declare function useScreenTracking(): void;
+export declare function useTrackClick(event: string, properties?: Record<string, any>): () => void;
+export declare function useTrackSubmit(event: string, properties?: Record<string, any>): (e: FormEvent<HTMLFormElement>) => void;
+export declare function useTrackEvent(): (event: string, properties?: Record<string, any>) => void;
+export declare function useAutoTrack(componentName: string, properties?: Record<string, any>): void;
+export declare function usePageView(pageName: string, properties?: Record<string, any>): void;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAoBnD,wBAAgB,WAAW,IAAI,oBAAoB,CAQlD;AAKD,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAUnF;AAKD,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAUrF;AAaD,wBAAgB,iBAAiB,IAAI,IAAI,CAsCxC;AAWD,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,IAAI,CAMzF;AAWD,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC/B,CAAC,CAAC,EAAE,SAAS,CAAC,eAAe,CAAC,KAAK,IAAI,CAMzC;AAcD,wBAAgB,aAAa,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,IAAI,CAQzF;AAiBD,wBAAgB,YAAY,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAoB1F;AAsBD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAqBpF"}

package/dist/hooks.js

@@ -0,0 +1,120 @@
+import { useContext, useEffect, useRef } from "react";
+import { DashgramContext } from "./provider";
+let useLocation = null;
+try {
+    if (typeof require !== "undefined" && require) {
+        const router = require("react-router-dom");
+        useLocation = router.useLocation;
+    }
+}
+catch {
+}
+export function useDashgram() {
+    const context = useContext(DashgramContext);
+    if (!context) {
+        throw new Error("useDashgram must be used within DashgramProvider");
+    }
+    return context;
+}
+export function useTrackMount(event, properties) {
+    const { track, isInitialized } = useDashgram();
+    const hasTracked = useRef(false);
+    useEffect(() => {
+        if (isInitialized && !hasTracked.current) {
+            track(event, properties);
+            hasTracked.current = true;
+        }
+    }, [isInitialized, event, properties, track]);
+}
+export function useTrackUnmount(event, properties) {
+    const { track, isInitialized } = useDashgram();
+    useEffect(() => {
+        return () => {
+            if (isInitialized) {
+                track(event, properties);
+            }
+        };
+    }, [isInitialized, event, properties, track]);
+}
+export function useScreenTracking() {
+    const { track, isInitialized } = useDashgram();
+    if (!useLocation) {
+        const isDev = typeof process !== "undefined" && process?.env?.NODE_ENV !== "production";
+        if (isDev) {
+            console.warn("Dashgram: useScreenTracking requires react-router-dom. " + "Install it or use manual screen tracking.");
+        }
+        return;
+    }
+    const location = useLocation();
+    const previousPath = useRef("");
+    useEffect(() => {
+        if (!isInitialized) {
+            return;
+        }
+        const currentPath = location.pathname;
+        if (currentPath === previousPath.current) {
+            return;
+        }
+        previousPath.current = currentPath;
+        track("screen_view", {
+            path: currentPath,
+            search: location.search,
+            hash: location.hash,
+            state: location.state
+        });
+    }, [location, isInitialized, track]);
+}
+export function useTrackClick(event, properties) {
+    const { track } = useDashgram();
+    return () => {
+        track(event, properties);
+    };
+}
+export function useTrackSubmit(event, properties) {
+    const { track } = useDashgram();
+    return (_e) => {
+        track(event, properties);
+    };
+}
+export function useTrackEvent() {
+    const { track, isInitialized } = useDashgram();
+    return (event, properties) => {
+        if (isInitialized) {
+            track(event, properties);
+        }
+    };
+}
+export function useAutoTrack(componentName, properties) {
+    const { track, isInitialized } = useDashgram();
+    const hasTrackedMount = useRef(false);
+    useEffect(() => {
+        if (isInitialized && !hasTrackedMount.current) {
+            track(`${componentName}_mounted`, properties);
+            hasTrackedMount.current = true;
+        }
+    }, [isInitialized, componentName, properties, track]);
+    useEffect(() => {
+        return () => {
+            if (isInitialized) {
+                track(`${componentName}_unmounted`, properties);
+            }
+        };
+    }, [isInitialized, componentName, properties, track]);
+}
+export function usePageView(pageName, properties) {
+    const { track, isInitialized } = useDashgram();
+    const previousPage = useRef("");
+    useEffect(() => {
+        if (!isInitialized) {
+            return;
+        }
+        if (pageName === previousPage.current) {
+            return;
+        }
+        previousPage.current = pageName;
+        track("page_view", {
+            page: pageName,
+            ...properties
+        });
+    }, [isInitialized, pageName, properties, track]);
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { DashgramProvider, DashgramContext } from "./provider";
+export type { DashgramProviderProps } from "./provider";
+export { useDashgram, useTrackEvent, useTrackMount, useTrackUnmount, useScreenTracking, usePageView, useAutoTrack, useTrackClick, useTrackSubmit } from "./hooks";
+export type { DashgramContextValue, DashgramConfig, EventProperties, TrackLevel } from "./types";
+export { default as DashgramMini } from "@dashgram/javascript";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"AAMA,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAC9D,YAAY,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AAEvD,OAAO,EACL,WAAW,EACX,aAAa,EACb,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,YAAY,EACZ,aAAa,EACb,cAAc,EACf,MAAM,SAAS,CAAA;AAEhB,YAAY,EAAE,oBAAoB,EAAE,cAAc,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAGhG,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,sBAAsB,CAAA"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { DashgramProvider, DashgramContext } from "./provider";
+export { useDashgram, useTrackEvent, useTrackMount, useTrackUnmount, useScreenTracking, usePageView, useAutoTrack, useTrackClick, useTrackSubmit } from "./hooks";
+export { default as DashgramMini } from "@dashgram/javascript";

package/dist/provider.d.ts

@@ -0,0 +1,9 @@
+import React from "react";
+import type { DashgramConfig } from "@dashgram/javascript";
+import type { DashgramContextValue } from "./types";
+export declare const DashgramContext: React.Context<DashgramContextValue | null>;
+export interface DashgramProviderProps extends DashgramConfig {
+    children: React.ReactNode;
+}
+export declare function DashgramProvider({ children, projectId, trackLevel, apiUrl, batchSize, flushInterval, debug, disabled, onError }: DashgramProviderProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAqD,MAAM,OAAO,CAAA;AAEzE,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,sBAAsB,CAAA;AACtE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAKnD,eAAO,MAAM,eAAe,4CAAmD,CAAA;AAK/E,MAAM,WAAW,qBAAsB,SAAQ,cAAc;IAC3D,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAC1B;AAKD,wBAAgB,gBAAgB,CAAC,EAC/B,QAAQ,EACR,SAAS,EACT,UAAc,EACd,MAAM,EACN,SAAS,EACT,aAAa,EACb,KAAK,EACL,QAAQ,EACR,OAAO,EACR,EAAE,qBAAqB,2CAmEvB"}

package/dist/provider.js

@@ -0,0 +1,64 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useEffect, useRef, useState } from "react";
+import DashgramMini from "@dashgram/javascript";
+export const DashgramContext = createContext(null);
+export function DashgramProvider({ children, projectId, trackLevel = 2, apiUrl, batchSize, flushInterval, debug, disabled, onError }) {
+    const [isInitialized, setIsInitialized] = useState(false);
+    const [currentTrackLevel, setCurrentTrackLevel] = useState(trackLevel);
+    const initRef = useRef(false);
+    useEffect(() => {
+        if (initRef.current) {
+            return;
+        }
+        initRef.current = true;
+        try {
+            DashgramMini.init({
+                projectId,
+                trackLevel,
+                apiUrl,
+                batchSize,
+                flushInterval,
+                debug,
+                disabled,
+                onError
+            });
+            setIsInitialized(true);
+        }
+        catch (error) {
+            console.error("Dashgram: Failed to initialize", error);
+        }
+        return () => {
+            DashgramMini.shutdown();
+        };
+    }, [projectId, trackLevel, apiUrl, batchSize, flushInterval, debug, disabled, onError]);
+    const value = {
+        track: (event, properties) => {
+            if (isInitialized) {
+                DashgramMini.track(event, properties);
+            }
+        },
+        isInitialized,
+        flush: async () => {
+            if (isInitialized) {
+                await DashgramMini.flush();
+            }
+        },
+        setTrackLevel: level => {
+            if (isInitialized) {
+                DashgramMini.setTrackLevel(level);
+                setCurrentTrackLevel(level);
+            }
+        },
+        getTrackLevel: () => {
+            return currentTrackLevel;
+        },
+        shutdown: () => {
+            if (isInitialized) {
+                DashgramMini.shutdown();
+                setIsInitialized(false);
+                initRef.current = false;
+            }
+        }
+    };
+    return _jsx(DashgramContext.Provider, { value: value, children: children });
+}

package/dist/types.d.ts

@@ -0,0 +1,11 @@
+import type { DashgramConfig, EventProperties, TrackLevel } from "@dashgram/javascript";
+export type { DashgramConfig, EventProperties, TrackLevel };
+export interface DashgramContextValue {
+    track: (event: string, properties?: EventProperties) => void;
+    isInitialized: boolean;
+    flush: () => Promise<void>;
+    setTrackLevel: (level: TrackLevel) => void;
+    getTrackLevel: () => TrackLevel | undefined;
+    shutdown: () => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEvF,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,UAAU,EAAE,CAAA;AAK3D,MAAM,WAAW,oBAAoB;IAEnC,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,eAAe,KAAK,IAAI,CAAA;IAG5D,aAAa,EAAE,OAAO,CAAA;IAGtB,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAG1B,aAAa,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAA;IAG1C,aAAa,EAAE,MAAM,UAAU,GAAG,SAAS,CAAA;IAG3C,QAAQ,EAAE,MAAM,IAAI,CAAA;CACrB"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@dashgram/react",
+  "version": "1.0.1",
+  "description": "React wrapper for Dashgram Analytics SDK",
+  "main": "dist/index.js",
+  "module": "dist/index.esm.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "type-check": "tsc --noEmit",
+    "test": "echo \"Tests require @testing-library/react and jest. See README for setup.\""
+  },
+  "keywords": [
+    "dashgram",
+    "analytics",
+    "react",
+    "telegram",
+    "mini-apps"
+  ],
+  "author": "Dashgram",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dashgram/dashgram-react.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dashgram/dashgram-react/issues"
+  },
+  "homepage": "https://dashgram.io",
+  "peerDependencies": {
+    "react": "^18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react-router-dom": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@dashgram/javascript": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.2.0",
+    "react": "^18.2.0",
+    "typescript": "^5.3.3"
+  }
+}