Installation Guide
Install Pulsora analytics using NPM for modern applications or CDN for traditional websites. Both methods take less than 5 minutes to set up.
NPM Installation
Prerequisites
- Node.js 16.x or higher
- NPM or Yarn package manager
Install the Package
# Using npm
npm install @pulsora/core
# Using yarn
yarn add @pulsora/core
# Using pnpm
pnpm add @pulsora/coreBasic Setup
// Import the Pulsora class
import { Pulsora } from '@pulsora/core';
// Create a new instance
const pulsora = new Pulsora();
// Initialize with your API token
pulsora.init({
apiToken: 'your-api-token-here',
});TypeScript Setup
Pulsora includes TypeScript definitions out of the box:
import { Pulsora, PulsoraConfig } from '@pulsora/core';
const config: PulsoraConfig = {
apiToken: 'your-api-token-here',
debug: process.env.NODE_ENV === 'development',
};
const pulsora = new Pulsora();
pulsora.init(config);CDN Installation
Basic Setup
Add the Pulsora script tag to your HTML, preferably just before the closing </body> tag:
<script
async
src="https://cdn.pulsora.co/v1/pulsora.min.js"
data-token="your-api-token-here"
></script>Configuration via Data Attributes
You can configure Pulsora using data attributes on the script tag:
<script
async
src="https://cdn.pulsora.co/v1/pulsora.min.js"
data-token="your-api-token-here"
data-auto-pageviews="true"
data-debug="false"
></script>Using the Global Object
Once loaded, Pulsora is available as window.pulsora:
<script>
// Wait for Pulsora to load
window.addEventListener('load', function () {
// Track an event
window.pulsora.event('page_loaded');
});
</script>Framework-Specific Installation
React
For React applications, we recommend using our dedicated React package:
npm install @pulsora/react @pulsora/coreSee the React integration guide for detailed setup instructions.
Next.js
npm install @pulsora/coreCreate a provider component:
// app/providers/analytics.tsx
'use client';
import { Pulsora } from '@pulsora/core';
import { usePathname } from 'next/navigation';
import { useEffect } from 'react';
const pulsora = new Pulsora();
pulsora.init({ apiToken: process.env.NEXT_PUBLIC_PULSORA_TOKEN });
export function AnalyticsProvider({ children }) {
const pathname = usePathname();
useEffect(() => {
pulsora.pageview();
}, [pathname]);
return children;
}Vue.js
npm install @pulsora/coreCreate a Vue plugin:
// plugins/pulsora.js
import { Pulsora } from '@pulsora/core';
export default {
install(app, options) {
const pulsora = new Pulsora();
pulsora.init({ apiToken: options.apiToken });
app.config.globalProperties.$pulsora = pulsora;
app.provide('pulsora', pulsora);
},
};Verification
After installation, verify that Pulsora is working correctly:
1. Check Browser Console
Enable debug mode to see events in the console:
pulsora.init({
apiToken: 'your-token',
debug: true,
});You should see logs like:
[Pulsora] Initialized with token: your-t***
[Pulsora] Pageview tracked: /current-page
[Pulsora] Event tracked: button_click2. Check Network Tab
- Open your browser's Developer Tools
- Go to the Network tab
- Filter by "pulsora" or "ingest"
- You should see POST requests to
https://api.pulsora.co/ingest
3. Check Your Dashboard
Log into your Pulsora dashboard to see real-time data from your installation.
Troubleshooting
Script Not Loading (CDN)
Symptoms:
pulsora is not definederror- No network requests to pulsora.co
- Script tag visible but not executing
Solutions:
- Check Content Security Policy
<!-- Add to your HTML <head> -->
<meta
http-equiv="Content-Security-Policy"
content="script-src 'self' https://cdn.pulsora.co; connect-src 'self' https://api.pulsora.co;"
/>- Verify API Token
- Token should start with
pub_ - Get from dashboard → Settings → API Tokens
- Don't use secret tokens (
sec_) in browser
- Check HTTPS
- Pulsora requires HTTPS in production
- Use
http://localhostfor local development
Module Not Found (NPM)
Error: Cannot find module '@pulsora/core'
Solutions:
- Reinstall package:
rm -rf node_modules package-lock.json
npm install- Check package.json:
{
"dependencies": {
"@pulsora/core": "^1.0.0"
}
}- Clear build cache:
# Webpack
rm -rf .cache dist
# Vite
rm -rf dist node_modules/.viteNo Events in Dashboard
Possible causes:
- Wrong API Token
// ❌ Wrong - using secret token in browser
apiToken: 'sec_xxx';
// ✅ Correct - using public token
apiToken: 'pub_xxx';- Domain Not Whitelisted
- Go to Dashboard → Settings → Websites
- Add your domain (e.g.,
example.com) - Include all subdomains if needed
- Ad Blocker Enabled
- Test in incognito mode
- Check browser extensions
- Use server-side tracking for critical events
- Network Issues
// Enable debug to see network errors
pulsora.init({
apiToken: 'pub_xxx',
debug: true, // Check console for errors
});TypeScript Errors
Error: Property 'pulsora' does not exist on type 'Window'
Solution:
// Create types/pulsora.d.ts
import type { PulsoraCore } from '@pulsora/core';
declare global {
interface Window {
pulsora: PulsoraCore;
}
}
export {};Error: Cannot find module '@pulsora/core' or its corresponding type declarations
Solution:
# Install latest version
npm install @pulsora/core@latest
# If still not working, check tsconfig.json
{
"compilerOptions": {
"moduleResolution": "node",
"esModuleInterop": true
}
}Build Errors
Webpack: Module parse failed: Unexpected token
Solution:
// webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.js$/,
include: /node_modules\/@pulsora/,
use: {
loader: 'babel-loader',
options: {
presets: ['@babel/preset-env'],
},
},
},
],
},
};Vite: [plugin:vite:import-analysis] Failed to resolve import
Solution:
// vite.config.js
import { defineConfig } from 'vite';
export default defineConfig({
optimizeDeps: {
include: ['@pulsora/core'],
},
});Performance Issues
Large Bundle Size
Use dynamic imports for code splitting:
// Load Pulsora only when needed
const initAnalytics = async () => {
const { Pulsora } = await import('@pulsora/core');
const pulsora = new Pulsora();
pulsora.init({ apiToken: 'pub_xxx' });
};
// Call on user interaction or route change
initAnalytics();Next Steps
Now that you have Pulsora installed: