{"_id":"@domino-run/analytics-js","_rev":"2-981bc874a6af4c5e6fe71593067bf77d","name":"@domino-run/analytics-js","dist-tags":{"latest":"1.0.1"},"versions":{"0.1.0":{"name":"@domino-run/analytics-js","version":"0.1.0","keywords":["analytics","tracking","domino","web-analytics","user-tracking","events"],"_id":"@domino-run/analytics-js@0.1.0","maintainers":[{"name":"peter_domino","email":"peter@domino.run"}],"homepage":"https://github.com/GetDomino/analytics-monorepo/tree/main/packages/web#readme","bugs":{"url":"https://github.com/GetDomino/analytics-monorepo/issues"},"dist":{"shasum":"9645ecbe0f97fb0a0027c49e04604182d4863904","tarball":"https://registry.npmjs.org/@domino-run/analytics-js/-/analytics-js-0.1.0.tgz","fileCount":4,"integrity":"sha512-VwOBzvdpqfk+IaPTGptCFRw7rQVqxDsMi1fRA+CpdTVVSKI92MVBrpMgneRVROynZM5BfP+5aJEosZb0xMhvEg==","signatures":[{"sig":"MEUCIFtLVsHre9ZvgfS5t55rAizQyJHP5p43xYfWP3d3WzWHAiEA63Bydr0J5mZmZbtrL/XtP8m/+5FHHD1/X9exoCCHb7k=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":20948},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"}},"gitHead":"ee9e704d603e9dcb4b75155c081ffc2cb2d49641","scripts":{"test":"jest","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"peter_domino","email":"peter@domino.run"},"repository":{"url":"git+https://github.com/GetDomino/analytics-monorepo.git","type":"git"},"_npmVersion":"10.8.2","description":"Client-side analytics tracking library for Domino Analytics","directories":{},"_nodeVersion":"20.18.1","_hasShrinkwrap":false,"devDependencies":{"jest":"^29.0.0","ts-jest":"^29.0.0","typescript":"^5.0.0","@types/jest":"^29.0.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/analytics-js_0.1.0_1737985218289_0.5701235991998288","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@domino-run/analytics-js","version":"1.0.0","keywords":["analytics","tracking","domino","web-analytics","user-tracking","events"],"_id":"@domino-run/analytics-js@1.0.0","maintainers":[{"name":"peter_domino","email":"peter@domino.run"}],"homepage":"https://github.com/GetDomino/analytics-monorepo/tree/main/packages/web#readme","bugs":{"url":"https://github.com/GetDomino/analytics-monorepo/issues"},"dist":{"shasum":"d8b84234c5621d910c550cd862f271a2593c1632","tarball":"https://registry.npmjs.org/@domino-run/analytics-js/-/analytics-js-1.0.0.tgz","fileCount":4,"integrity":"sha512-c5LerdgVBtl1bE+2EKiMuQxECupIAlQKgVB55s11EsS+z92hymRLV/o96C/0LFF/sNztuEKXtWQbuQUq5brpYA==","signatures":[{"sig":"MEQCICzUH06keFMJkapXDFWxBSJANt2QygqMZaOsniDRUt7HAiB8Lyj3UcDNnzVNFz0ZbNGrWUP/brsC5rDH4CoBizy8Ng==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":20944},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"}},"gitHead":"e76404c8da43b1009888a347af0f28ef3a896bce","scripts":{"test":"jest","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"peter_domino","email":"peter@domino.run"},"repository":{"url":"git+https://github.com/GetDomino/analytics-monorepo.git","type":"git"},"_npmVersion":"10.8.2","description":"Client-side analytics tracking library for Domino Analytics","directories":{},"_nodeVersion":"20.18.1","_hasShrinkwrap":false,"devDependencies":{"jest":"^29.0.0","ts-jest":"^29.0.0","typescript":"^5.0.0","@types/jest":"^29.0.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/analytics-js_1.0.0_1739975585112_0.6249026988733255","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@domino-run/analytics-js","version":"1.0.1","description":"Client-side analytics tracking library for Domino Analytics","type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"}},"scripts":{"build":"tsc","test":"jest","prepublishOnly":"npm run build"},"keywords":["analytics","tracking","domino","web-analytics","user-tracking","events"],"repository":{"type":"git","url":"git+https://github.com/GetDomino/analytics-monorepo.git"},"bugs":{"url":"https://github.com/GetDomino/analytics-monorepo/issues"},"homepage":"https://github.com/GetDomino/analytics-monorepo/tree/main/packages/web#readme","devDependencies":{"@types/node":"^20.0.0","typescript":"^5.0.0","jest":"^29.0.0","@types/jest":"^29.0.0","ts-jest":"^29.0.0"},"_id":"@domino-run/analytics-js@1.0.1","gitHead":"e76404c8da43b1009888a347af0f28ef3a896bce","_nodeVersion":"20.18.1","_npmVersion":"10.8.2","dist":{"integrity":"sha512-3miMM34PHOWv9OTBQHoZAEfpC04NOT1mXdj4p6Re/DdFvVjVAUKd2KCXmzxe1rYQvk2nni5T/46mh/vTvlUBFg==","shasum":"c3c3d71c6fa8a046c8ea77f788538ed198239e36","tarball":"https://registry.npmjs.org/@domino-run/analytics-js/-/analytics-js-1.0.1.tgz","fileCount":4,"unpackedSize":20944,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAaGCCIJYD0ry01odn+4yHwgZJMcTxvRh/RjwsTTFFqgAiBjHEGRGeKk9kOUqq4HZtIEeBrrrDQjCCACgjRf31WmNw=="}]},"_npmUser":{"name":"peter_domino","email":"peter@domino.run"},"directories":{},"maintainers":[{"name":"peter_domino","email":"peter@domino.run"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/analytics-js_1.0.1_1739975744044_0.9985562248024928"},"_hasShrinkwrap":false}},"time":{"created":"2025-01-27T13:40:18.168Z","modified":"2025-02-19T14:35:44.440Z","0.1.0":"2025-01-27T13:40:18.470Z","1.0.0":"2025-02-19T14:33:05.294Z","1.0.1":"2025-02-19T14:35:44.236Z"},"bugs":{"url":"https://github.com/GetDomino/analytics-monorepo/issues"},"homepage":"https://github.com/GetDomino/analytics-monorepo/tree/main/packages/web#readme","keywords":["analytics","tracking","domino","web-analytics","user-tracking","events"],"repository":{"type":"git","url":"git+https://github.com/GetDomino/analytics-monorepo.git"},"description":"Client-side analytics tracking library for Domino Analytics","maintainers":[{"name":"peter_domino","email":"peter@domino.run"}],"readme":"# @domino-run/analytics-js\n\nClient-side analytics tracking library for Domino Analytics. Track user behavior, page views, custom events, and referrals with ease.\n\n## Features\n\n- 🪶 **Lightweight** - Zero dependencies, just native `fetch`\n- 📊 **Optional Page Tracking** - Configurable automatic page view tracking\n- 🔄 **Session Management** - Browser session-based tracking\n- 👤 **User Identification** - Easy user identity management\n- 🎯 **Custom Events** - Track any custom event with properties\n- 🔗 **Referral System** - Built-in referral system with wallet support\n- 📱 **Browser Support** - Works in all modern browsers\n- 🔒 **Type Safe** - Written in TypeScript with full type definitions\n\n## Installation\n\n```bash\nnpm install @domino-run/analytics-js\n# or\nyarn add @domino-run/analytics-js\n# or\npnpm add @domino-run/analytics-js\n```\n\n## Quick Start\n\n```typescript\nimport { DominoAnalytics } from '@domino-run/analytics-js';\n\n// Initialize with your API key\nconst analytics = new DominoAnalytics({\n  apiKey: 'your-api-key',\n  // Optional: enable automatic page tracking\n  pageTracking: {\n    enabled: true,\n    trackHistory: true // also track history changes (back/forward)\n  },\n  // Optional: specify referral type\n  referralType: 'user_id' // or 'wallet' for crypto applications\n});\n\n// Track a custom event\nanalytics.track({\n  eventType: 'button_click',\n  properties: {\n    buttonId: 'signup-button',\n    buttonText: 'Sign Up Now'\n  }\n});\n\n// Identify a user\nanalytics.identify({\n  externalId: 'user-123', // or wallet address for crypto apps\n  properties: {\n    name: 'John Doe',\n    email: 'john@example.com',\n    plan: 'premium'\n  }\n});\n```\n\n## Configuration\n\n### Page Tracking\n\nPage tracking is disabled by default. To enable it, use the `pageTracking` configuration:\n\n```typescript\nconst analytics = new DominoAnalytics({\n  apiKey: 'your-api-key',\n  pageTracking: {\n    enabled: true,     // Enable automatic page view tracking\n    trackHistory: true // Optional: track history changes (back/forward navigation)\n  }\n});\n```\n\nWhen enabled, it will automatically track:\n- Initial page load (`enabled: true`)\n- Browser history changes if `trackHistory: true` (back/forward navigation)\n\nYou can also manually track page views:\n```typescript\nanalytics.track({\n  eventType: 'page_view',\n  pageUrl: window.location.href,\n  referrer: document.referrer\n});\n```\n\n## Session Management\n\nThe library uses browser session storage for managing sessions:\n\n- Each browser session gets a unique session ID\n- Session persists across page refreshes\n- Session is cleared when the browser/tab is closed\n- New session is created when browser is reopened\n- Sessions are automatically managed, no configuration needed\n\n## Referral System\n\nThe library includes a built-in referral system that supports both traditional user IDs and crypto wallet addresses.\n\n### Referral Types\n\nThere are two types of referral systems:\n\n1. **User ID Based** (`referralType: 'user_id'`):\n   - Default referral system\n   - Uses internal or external user IDs for referrals\n   - Validates referrer exists in the system\n\n2. **Wallet Based** (`referralType: 'wallet'`):\n   - Designed for crypto applications\n   - Uses wallet addresses as referral IDs\n   - Validates wallet address format (0x...)\n   - Automatically creates user records for new wallet addresses\n\n### Referral Flow\n\n1. **Generating Referral Links**\n```typescript\n// After identifying a user\nconst referralLink = analytics.getReferralLink();\n// Or with custom base URL\nconst customLink = analytics.getReferralLink('https://example.com/signup');\n```\n\n2. **Handling Referrals**\n- Referral data is automatically detected from URL parameters\n- Referral info is stored until the referred user identifies\n- Referral relationship is created upon user identification\n- Referral data persists across sessions until used\n\nExample flow:\n\n```typescript\n// User A: Generate referral link\nawait analytics.identify({ externalId: 'user_a' });\nconst link = analytics.getReferralLink(); // https://example.com?ref=user_a\n\n// User B: Clicks link and later identifies\nawait analytics.identify({\n  externalId: 'user_b',\n  properties: { name: 'User B' }\n}); // Referral is automatically tracked\n```\n\n## API Reference\n\n### Initialization\n\n```typescript\nconst analytics = new DominoAnalytics({\n  apiKey: string;           // Required: Your API key\n  endpoint?: string;        // Optional: Custom API endpoint\n  referralType?: 'wallet' | 'user_id'; // Optional: Referral system type\n  pageTracking?: {         // Optional: Automatic page view tracking\n    enabled: boolean;      // Enable/disable page tracking\n    trackHistory?: boolean;// Track history changes (back/forward)\n  };\n});\n```\n\n### Tracking Events\n\n```typescript\nanalytics.track({\n  eventType: string;           // Required: Event name\n  properties?: {              // Optional: Event properties\n    [key: string]: any;\n  };\n  pageUrl?: string;          // Optional: Override page URL\n  referrer?: string;         // Optional: Override referrer\n});\n```\n\n### Identifying Users\n\n```typescript\nanalytics.identify({\n  externalId: string;         // Required: User ID or wallet address\n  properties?: {             // Optional: User properties\n    [key: string]: any;\n  };\n});\n```\n\n## Best Practices\n\n### Event Naming\n\n- Use snake_case for event names\n- Be consistent with naming conventions\n- Use descriptive but concise names\n\nExample events:\n```typescript\nanalytics.track({ eventType: 'page_view' });\nanalytics.track({ eventType: 'button_click' });\nanalytics.track({ eventType: 'form_submit' });\nanalytics.track({ eventType: 'purchase_complete' });\n```\n\n### Properties\n\n- Include relevant context in properties\n- Avoid sensitive information\n- Use consistent property names\n\nExample:\n```typescript\nanalytics.track({\n  eventType: 'button_click',\n  properties: {\n    button_id: 'signup-cta',\n    button_text: 'Start Free Trial',\n    page_section: 'hero',\n    variant: 'A'\n  }\n});\n```\n\n### User Properties\n\n- Include business-relevant user data\n- Update properties when they change\n- Avoid sensitive data\n\nExample:\n```typescript\nanalytics.identify({\n  externalId: 'user_123',\n  properties: {\n    name: 'John Doe',\n    email: 'john@example.com',\n    plan: 'premium',\n    company: 'Acme Inc'\n  }\n});\n```\n\n### Referral Best Practices\n\n- Generate referral links only after user identification\n- Use descriptive base URLs for referral links\n- Add UTM parameters for better tracking\n- Test referral flows in incognito mode\n\nExample with UTM parameters:\n```typescript\nconst baseUrl = 'https://example.com/special-offer';\nconst referralLink = analytics.getReferralLink(baseUrl);\nconst trackingUrl = new URL(referralLink);\ntrackingUrl.searchParams.append('utm_source', 'referral');\ntrackingUrl.searchParams.append('utm_medium', 'user_share');\n```\n\n## Error Handling\n\nThe library includes built-in error handling with typed errors:\n\n```typescript\ntry {\n  await analytics.track({\n    eventType: 'purchase',\n    properties: { amount: 99.99 }\n  });\n} catch (error) {\n  if (error.status === 401) {\n    // Handle unauthorized error\n  }\n}\n```\n\n## Browser Support\n\nSupports all modern browsers with Fetch API:\n- Chrome 42+\n- Firefox 39+\n- Safari 10.1+\n- Edge 14+\n\n## Framework Integration\n\n### React\n\n```typescript\n// src/lib/analytics.ts\nimport { DominoAnalytics } from '@domino-run/analytics-js';\n\nexport const analytics = new DominoAnalytics({\n  apiKey: process.env.REACT_APP_ANALYTICS_KEY!,\n  pageTracking: {\n    enabled: true,\n    trackHistory: true\n  }\n});\n\n// Optional: Create hooks for easier usage\nimport { useEffect } from 'react';\n\nexport function usePageTracking() {\n  useEffect(() => {\n    analytics.track({\n      eventType: 'page_view',\n      pageUrl: window.location.href\n    });\n  }, []);\n}\n\nexport function useIdentify(userId: string, properties?: Record<string, any>) {\n  useEffect(() => {\n    if (userId) {\n      analytics.identify({\n        externalId: userId,\n        properties\n      });\n    }\n  }, [userId, properties]);\n}\n```\n\nUsage in components:\n\n```tsx\n// src/App.tsx\nimport { analytics, usePageTracking } from './lib/analytics';\n\nfunction App() {\n  // Track page views automatically\n  usePageTracking();\n\n  return (\n    <div>\n      <button onClick={() => {\n        analytics.track({\n          eventType: 'button_click',\n          properties: { buttonId: 'signup' }\n        });\n      }}>\n        Sign Up\n      </button>\n    </div>\n  );\n}\n\n// src/UserProfile.tsx\nimport { useIdentify } from './lib/analytics';\n\nfunction UserProfile({ user }) {\n  // Identify user when component mounts\n  useIdentify(user.id, {\n    name: user.name,\n    email: user.email\n  });\n\n  return <div>Welcome, {user.name}!</div>;\n}\n```\n\n### Vue\n\n```typescript\n// src/plugins/analytics.ts\nimport { DominoAnalytics } from '@domino-run/analytics-js';\nimport type { App } from 'vue';\n\nexport const analytics = new DominoAnalytics({\n  apiKey: import.meta.env.VITE_ANALYTICS_KEY,\n  pageTracking: {\n    enabled: true,\n    trackHistory: true\n  }\n});\n\n// Create Vue plugin\nexport const analyticsPlugin = {\n  install: (app: App) => {\n    app.config.globalProperties.$analytics = analytics;\n    \n    // Optional: Create composables\n    app.provide('analytics', analytics);\n  }\n};\n\n// Optional: Create composables\nimport { onMounted, watch } from 'vue';\n\nexport function usePageTracking() {\n  onMounted(() => {\n    analytics.track({\n      eventType: 'page_view',\n      pageUrl: window.location.href\n    });\n  });\n}\n\nexport function useIdentify(userId: string, properties?: Record<string, any>) {\n  watch(() => userId, (newId) => {\n    if (newId) {\n      analytics.identify({\n        externalId: newId,\n        properties\n      });\n    }\n  }, { immediate: true });\n}\n```\n\nUsage in components:\n\n```vue\n<!-- src/App.vue -->\n<script setup lang=\"ts\">\nimport { analytics, usePageTracking } from './plugins/analytics';\n\n// Track page views automatically\nusePageTracking();\n\nconst handleClick = () => {\n  analytics.track({\n    eventType: 'button_click',\n    properties: { buttonId: 'signup' }\n  });\n};\n</script>\n\n<template>\n  <button @click=\"handleClick\">Sign Up</button>\n</template>\n\n<!-- src/UserProfile.vue -->\n<script setup lang=\"ts\">\nimport { useIdentify } from './plugins/analytics';\n\nconst props = defineProps<{\n  user: {\n    id: string;\n    name: string;\n    email: string;\n  }\n}>();\n\n// Identify user when component mounts or user changes\nuseIdentify(props.user.id, {\n  name: props.user.name,\n  email: props.user.email\n});\n</script>\n\n<template>\n  <div>Welcome, {{ user.name }}!</div>\n</template>\n```\n\n### Using with Router\n\nFor both React and Vue, you can integrate with the router for better page tracking:\n\n#### React Router\n\n```typescript\nimport { useEffect } from 'react';\nimport { useLocation } from 'react-router-dom';\nimport { analytics } from './lib/analytics';\n\nexport function useRouteTracking() {\n  const location = useLocation();\n\n  useEffect(() => {\n    analytics.track({\n      eventType: 'page_view',\n      pageUrl: window.location.href,\n      properties: {\n        path: location.pathname,\n        search: location.search\n      }\n    });\n  }, [location]);\n}\n```\n\n#### Vue Router\n\n```typescript\nimport { useRoute } from 'vue-router';\nimport { watch } from 'vue';\nimport { analytics } from './plugins/analytics';\n\nexport function useRouteTracking() {\n  const route = useRoute();\n\n  watch(\n    () => route.fullPath,\n    () => {\n      analytics.track({\n        eventType: 'page_view',\n        pageUrl: window.location.href,\n        properties: {\n          path: route.path,\n          params: route.params,\n          query: route.query\n        }\n      });\n    },\n    { immediate: true }\n  );\n}\n```\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](https://github.com/GetDomino/analytics-monorepo/blob/main/CONTRIBUTING.md).\n\n## License\n\nMIT © [Domino Analytics](https://github.com/GetDomino) ","readmeFilename":"README.md"}