Quick Start Guide#

Get Pulsora analytics running on your website or application in just 5 minutes. This guide covers everything from installation to your first tracked event.

What You'll Learn#

By the end of this guide, you'll:

• ✅ Install Pulsora using NPM or CDN
• ✅ Track pageviews automatically
• ✅ Track custom events (button clicks, form submissions)
• ✅ Verify your setup is working
• ✅ Know where to go next

Prerequisites#

Before you begin, you'll need:

1. A Pulsora account (sign up here)
2. Your website's API token (found in your dashboard)
3. Node.js installed (for NPM installation) or ability to add script tags (for CDN)

Choose Your Installation Method#

Pulsora can be installed in two ways:

Option 1: NPM Installation (Recommended for Apps)#

Perfect for React, Vue, Angular, or any modern JavaScript application.

npm install @pulsora/core

Option 2: CDN Installation (Recommended for Websites)#

Perfect for WordPress, static sites, or any traditional website.

<script
  async
  src="https://cdn.pulsora.co/v1/pulsora.min.js"
  data-token="YOUR_API_TOKEN"
></script>

Basic Implementation#

NPM Implementation#

// 1. Import Pulsora
import { Pulsora } from '@pulsora/core';

// 2. Create and initialize tracker
const pulsora = new Pulsora();
pulsora.init({
  apiToken: 'YOUR_API_TOKEN', // Replace with your actual token
  autoPageviews: true, // Enable automatic pageview tracking
});

// 3. Track custom events (optional)
document.getElementById('signup-button')?.addEventListener('click', () => {
  pulsora.event('signup_click', {
    location: 'header',
    variant: 'blue',
  });
});

CDN Implementation#

<!-- 1. Add the script tag (usually before </body>) -->
<script
  async
  src="https://cdn.pulsora.co/v1/pulsora.min.js"
  data-token="YOUR_API_TOKEN"
></script>

<!-- 2. Track custom events (optional) -->
<script>
  // Wait for Pulsora to load
  window.addEventListener('load', function () {
    // Track button clicks
    document
      .getElementById('signup-button')
      ?.addEventListener('click', function () {
        window.pulsora.event('signup_click', {
          location: 'header',
          variant: 'blue',
        });
      });
  });
</script>

React Quick Start#

If you're using React, we have dedicated hooks that make integration even easier:

npm install @pulsora/react @pulsora/core

// App.jsx
import { PulsoraProvider } from '@pulsora/react';

function App() {
  return (
    <PulsoraProvider config={{ apiToken: 'YOUR_API_TOKEN' }}>
      <YourApp />
    </PulsoraProvider>
  );
}

// Component.jsx
import { usePageview, useEvent } from '@pulsora/react';

function MyComponent() {
  usePageview(); // Automatic pageview tracking
  const trackEvent = useEvent();

  return <button onClick={() => trackEvent('button_click')}>Click me</button>;
}

Verify Your Installation#

After implementing Pulsora, here's how to verify it's working:

1. Check the Network Tab

   • Open your browser's Developer Tools
   • Go to the Network tab
   • Look for requests to pulsora.co/api/ingest
   • You should see pageview and event requests

2. Check Your Dashboard

   • Log into your Pulsora dashboard
   • Navigate to your website
   • You should see real-time data within seconds

3. Enable Debug Mode (optional)

   pulsora.init({
     apiToken: 'YOUR_API_TOKEN',
     debug: true, // Logs all events to console
   });

What's Next?#

Now that you have basic tracking set up, explore these advanced features:

Track Custom Events#

Learn how to track specific user interactions:

• Event Tracking Guide
• Best Practices

Set Up Revenue Tracking#

Connect your payment processor to track revenue:

• Stripe Integration
• Paddle Integration
• Custom Webhooks

Advanced Configuration#

Customize Pulsora for your needs:

• Configuration Options
• SPA Support
• Privacy & Compliance

Common Questions#

Do I need to worry about GDPR?#

No! Pulsora is GDPR compliant by default. We don't use cookies or collect personal data. No consent banners required.

Learn more: Privacy & Compliance

Will this slow down my website?#

No! The Pulsora script is ~2KB and loads asynchronously with async attribute. It won't affect your page load times.

Performance impact: <0.1ms to page load time

Can I track custom events?#

Yes! You can track any event with custom properties like button clicks, form submissions, video plays, etc.

Example:

pulsora.event('video_play', {
  video_title: 'Product Demo',
  duration: 120,
  autoplay: false,
});

Learn more: Event tracking guide

How do I track revenue?#

Revenue tracking requires server-side integration with your payment processor (Stripe, Paddle, etc.).

Quick setup: Stripe integration | Revenue guide

What about ad blockers?#

Some ad blockers may block analytics. Pulsora uses a privacy-friendly domain and is less likely to be blocked than alternatives, but no solution is 100% effective.

Solution: Use server-side tracking for critical events.

Can I use this with [Framework]?#

Yes! Pulsora works with all frameworks. We have dedicated guides for:

• React / Next.js - Hooks and components
• Remix - SSR-ready integration
• React Router - SPA tracking
• Vanilla JS / Any framework - Use core package

Troubleshooting#

Events aren't showing in the dashboard#

Check these:

1. Verify your API token is correct
2. Open Network tab, look for requests to pulsora.co/api/ingest
3. Enable debug mode: pulsora.init({ apiToken: '...', debug: true })
4. Check browser console for errors

Common causes:

• Content Security Policy (CSP) blocking requests
• Ad blocker blocking analytics
• Wrong API token (should start with pub_)
• Network connectivity issues

Pageviews tracked multiple times#

Cause: You're calling pulsora.pageview() manually AND have autoPageviews: true

Solution: Choose one approach:

• Let Pulsora handle it: autoPageviews: true (recommended)
• Manual control: autoPageviews: false + call pageview() yourself

TypeScript errors#

Solution: Install type definitions (included in the package):

import type { PulsoraConfig } from '@pulsora/core';

const config: PulsoraConfig = {
  apiToken: process.env.PULSORA_TOKEN!,
  debug: true,
};

"Module not found" error#

Cause: Package not installed or import path incorrect

Solution:

npm install @pulsora/core
# or
npm install @pulsora/react @pulsora/core

Need Help?#

If you run into any issues:

1. Check our troubleshooting guide
2. Search our documentation
3. Contact support@pulsora.co
4. Join our Discord community

Ready for more? Dive into the Core Package Documentation to learn about all available features.