@narrowbeam/browser
v1.1.0
Published
Privacy-first browser analytics tracking for Narrowbeam
Maintainers
jprodahlReadme
@narrowbeam/browser
Privacy-first browser analytics tracking for Narrowbeam. Track page views and custom actions without cookies or persistent user identifiers.
Features
- 🔒 Privacy-First: No cookies, no persistent tracking
- 📊 Automatic Page View Tracking: Works with SPAs and traditional sites
- 🎯 Custom Action Tracking: Track button clicks and custom events
- 📱 Framework Agnostic: Works with React, Vue, Svelte, vanilla JS, etc.
- 🚀 Lightweight: Small bundle size with minimal dependencies
- 🔄 Dual Usage: Use via script tag or npm package
Installation
Via npm/yarn
npm install @narrowbeam/browser
# or
yarn add @narrowbeam/browserVia CDN (Script Tag)
Use a single script tag with the Narrowbeam loader:
<script>
(function(w,d,e,s,n) {
w=w[n]=w[n]||{q:[],onReady:function(c){w.q.push(c)}}
e=d.createElement(e);e.async=1;e.src=s
s=d.getElementsByTagName('script')[0];s.parentNode.insertBefore(e,s)
})(window,document,'script','https://unpkg.com/@narrowbeam/browser/dist/narrowbeam.min.js','narrowbeam')
window.narrowbeam.onReady(function() {
window.narrowbeam.init({
orgKey: 'your-org-key-here'
})
})
</script>Usage
NPM Package Usage
import { narrowbeam } from '@narrowbeam/browser'
// Initialize with your organization key
narrowbeam.init({
orgKey: 'your-org-key'
})
// Track custom actions
narrowbeam.trackAction('signup-click')
narrowbeam.trackAction('button-press')
// Manually track a page view
narrowbeam.trackPageView()
// Check for route changes (useful for SPAs)
narrowbeam.checkPageChange()Framework Examples
React
// src/analytics.js
import { narrowbeam } from '@narrowbeam/browser'
narrowbeam.init({
orgKey: 'your-org-key'
})// src/main.jsx or src/index.jsx
import './analytics'
import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App'
ReactDOM.createRoot(document.getElementById('root')).render(
<React.StrictMode>
<App />
</React.StrictMode>
)// src/App.jsx
import { narrowbeam } from '@narrowbeam/browser'
function App() {
const handleSignup = () => {
narrowbeam.trackAction('signup-click')
// ... your signup logic
}
return (
<button onClick={handleSignup}>
Sign Up
</button>
)
}Vue 3
<script setup>
import { onMounted } from 'vue'
import { narrowbeam } from '@narrowbeam/browser'
onMounted(() => {
narrowbeam.init({ orgKey: 'your-org-key' })
})
const handleSignup = () => {
narrowbeam.trackAction('signup-click')
// ... your signup logic
}
</script>
<template>
<button @click="handleSignup">Sign Up</button>
</template>Next.js (App Router)
// components/analytics.js
'use client'
import { narrowbeam } from '@narrowbeam/browser'
narrowbeam.init({
orgKey: process.env.NEXT_PUBLIC_NARROWBEAM_ORG_KEY
})
export default function Analytics() {
return null
}// app/layout.js
import Analytics from '@/components/analytics'
export default function RootLayout({ children }) {
return (
<html lang="en">
<body>
<Analytics />
{children}
</body>
</html>
)
}Automatic Action Tracking
You can track clicks automatically using data attributes without writing any JavaScript:
<!-- With npm package -->
<button data-narrowbeam-action-name="cta-click">
Get Started
</button>
<a href="/pricing" data-narrowbeam-action-name="pricing-link">
View Pricing
</a>When users click these elements, the action will be automatically tracked.
Configuration Options
narrowbeam.init({
orgKey: 'your-org-key' // Required: Your Narrowbeam organization key
})API Reference
narrowbeam.init(config)
Initialize the Narrowbeam tracking.
Parameters:
config.orgKey(string, required): Your organization key
narrowbeam.trackAction(actionName)
Track a custom action.
Parameters:
actionName(string, required): Name of the action to track
Example:
narrowbeam.trackAction('newsletter-signup')narrowbeam.trackPageView()
Manually track a page view. This is automatically called on initialization and route changes, but you can call it manually if needed.
Example:
narrowbeam.trackPageView()narrowbeam.checkPageChange()
Check if the current path has changed and track a page view if needed. Useful for framework-specific routing.
Example:
// In your router
router.afterEach(() => {
narrowbeam.checkPageChange()
})Features
UTM Parameter Tracking
Narrowbeam automatically captures UTM parameters from the URL:
utm_sourceutm_mediumutm_campaignutm_termutm_content
Single Page Application (SPA) Support
Narrowbeam automatically detects route changes in SPAs by monitoring:
popstateevents (browser back/forward)history.pushStatecallshistory.replaceStatecalls
Page Leave Tracking
Narrowbeam tracks when users leave pages using:
beforeunloadeventpagehideevent
Support
For issues and questions, please visit GitHub Issues.