Installation#

There are two ways to install @pulsora/core depending on your use case:

NPM Installation (Recommended for Apps)#

Perfect for React, Vue, Angular, or any JavaScript application with a build process.

1. Install the Package#

npm install @pulsora/core

Or using Yarn:

yarn add @pulsora/core

Or using pnpm:

pnpm add @pulsora/core

2. Import and Initialize#

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',
});

3. TypeScript Support#

TypeScript definitions are included. No need to install separate types:

import { Pulsora, PulsoraConfig } from '@pulsora/core';

const config: PulsoraConfig = {
  apiToken: 'your-api-token',
  debug: process.env.NODE_ENV === 'development',
};

const pulsora = new Pulsora();
pulsora.init(config);

CDN Installation (Recommended for Websites)#

Perfect for WordPress, static sites, or any website without a build process.

1. Add the Script Tag#

Add this script tag to your HTML, preferably in the <head> section:

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

2. Auto-Initialization#

The CDN version automatically:

Initializes tracking when the script loads
Tracks pageviews automatically
Provides a global window.pulsora object

3. Using the Global Object#

<script>
  // Wait for Pulsora to load
  window.addEventListener('load', function () {
    // Track a custom event
    window.pulsora.event('button_click', {
      button: 'cta',
    });
  });
</script>

4. Async-Safe Usage#

For immediate usage without waiting for load:

<script>
  // This pattern works even if Pulsora hasn't loaded yet
  window.pulsora = window.pulsora || {
    event: function () {
      (window.pulsora.q = window.pulsora.q || []).push(arguments);
    },
  };

  // Track events immediately
  window.pulsora.event('page_view');
</script>

Configuration Options#

Both installation methods support the same configuration:

{
  apiToken: 'your-api-token',        // Required
  endpoint: 'https://...',           // Optional: Custom endpoint
  autoPageviews: true,               // Optional: Auto-track pageviews (default: true)
  debug: false,                      // Optional: Enable debug logging (default: false)
  maxRetries: 10,                    // Optional: Max retry attempts (default: 10)
  retryBackoff: 1000                 // Optional: Initial retry delay in ms (default: 1000)
}

Verification#

Verify NPM Installation#

// Check if Pulsora is initialized
console.log('Pulsora initialized:', pulsora.isInitialized());

// Enable debug mode to see tracking calls
pulsora.init({
  apiToken: 'your-token',
  debug: true,
});

// You should see console logs for all tracking calls
pulsora.pageview();

Verify CDN Installation#

Open your browser's Developer Tools
Go to the Network tab
Reload your page
Look for:
- pulsora.min.js loading successfully
- POST requests to https://pulsora.co/api/ingest

Debug Mode#

Enable debug mode to troubleshoot:

// NPM
pulsora.init({
  apiToken: 'your-token',
  debug: true,
});

// CDN
<script
  async
  src="https://cdn.pulsora.co/v1/pulsora.min.js"
  data-token="your-token"
  data-debug="true"
></script>;

Environment-Specific Setup#

Development Environment#

const pulsora = new Pulsora();
pulsora.init({
  apiToken: process.env.PULSORA_TOKEN,
  debug: true,
  endpoint: 'http://localhost:8000/api/ingest', // Local testing
});

Production Environment#

const pulsora = new Pulsora();
pulsora.init({
  apiToken: process.env.PULSORA_TOKEN,
  debug: false,
});

Staging Environment#

const pulsora = new Pulsora();
pulsora.init({
  apiToken: process.env.PULSORA_STAGING_TOKEN,
  debug: true,
  endpoint: 'https://staging.pulsora.co/api/ingest',
});

Framework-Specific Installation#

React#

See our dedicated React package for the best React experience.

Vue.js#

// main.js
import { createApp } from 'vue';
import { Pulsora } from '@pulsora/core';

const app = createApp(App);

// Create Pulsora instance
const pulsora = new Pulsora();
pulsora.init({ apiToken: 'your-token' });

// Make it available globally
app.config.globalProperties.$pulsora = pulsora;

app.mount('#app');

Next.js#

For Next.js applications, see our Next.js integration guide.

Angular#

// app.module.ts
import { Pulsora } from '@pulsora/core';

@Injectable({
  providedIn: 'root',
})
export class AnalyticsService {
  private pulsora: Pulsora;

  constructor() {
    this.pulsora = new Pulsora();
    this.pulsora.init({ apiToken: 'your-token' });
  }

  trackEvent(name: string, data?: any) {
    this.pulsora.event(name, data);
  }
}

Security Best Practices#

1. Use Public Tokens Only#

Never use secret/private API tokens in the browser:

// ❌ WRONG - Never use secret tokens in browser
pulsora.init({ apiToken: 'sec_secret_token' });

// ✅ CORRECT - Use public tokens only
pulsora.init({ apiToken: 'pub_public_token' });

2. Domain Restrictions#

Configure allowed domains in your Pulsora dashboard to prevent token abuse.

3. Content Security Policy#

If using CSP, add Pulsora to your policy:

<meta
  http-equiv="Content-Security-Policy"
  content="script-src 'self' https://cdn.pulsora.co; 
           connect-src 'self' https://api.pulsora.co;"
/>

Troubleshooting#

Script Not Loading#

Check for ad blockers (some block analytics scripts)
Verify the script URL is correct
Check browser console for errors
Ensure your domain is allowed in Pulsora settings

Events Not Tracking#

Enable debug mode to see detailed logs
Check network tab for failed requests
Verify your API token is correct
Ensure you've called init() before tracking

TypeScript Errors#

# Ensure you have the latest version
npm update @pulsora/core

# If issues persist, try:
npm install --save-dev @types/node

Next Steps#

Now that you have Pulsora installed:

Need Help?#

📚 Check the API Reference
💬 Join our Discord Community
📧 Email support@pulsora.co