Configuration#

Configure @pulsora/core to match your specific tracking needs.

Configuration Options#

Full Configuration Object#

interface PulsoraConfig {
  apiToken: string; // Required: Your Pulsora API token
  endpoint?: string; // Optional: Custom API endpoint
  autoPageviews?: boolean; // Optional: Auto-track pageviews (default: true)
  debug?: boolean; // Optional: Enable debug logging (default: false)
  maxRetries?: number; // Optional: Max retry attempts (default: 10)
  retryBackoff?: number; // Optional: Initial retry delay in ms (default: 1000)
}

Basic Configuration#

const pulsora = new Pulsora();
pulsora.init({
  apiToken: 'pub_your_token_here',
});

Advanced Configuration#

const pulsora = new Pulsora();
pulsora.init({
  apiToken: 'pub_your_token_here',
  autoPageviews: false,
  debug: true,
  maxRetries: 5,
  retryBackoff: 2000,
});

Configuration Properties#

apiToken (required)#

Your Pulsora API token. Use public tokens only (starting with pub_).

pulsora.init({
  apiToken: 'pub_abc123...',
});

Getting your API token:

Log in to your Pulsora dashboard
Navigate to Website Settings
Copy the Public API Token

autoPageviews (optional)#

Automatically track pageviews on initialization and route changes.

Default: true

// Disable automatic pageview tracking
pulsora.init({
  apiToken: 'your-token',
  autoPageviews: false,
});

// Track pageviews manually
pulsora.pageview();

When to disable:

Custom pageview logic needed
Tracking specific pages only
Server-side rendered apps with hydration

debug (optional)#

Enable detailed console logging for troubleshooting.

Default: false

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

Debug output includes:

Initialization status
Tracking calls with payloads
Network requests and responses
Error messages with context
Retry attempts

maxRetries (optional)#

Maximum number of retry attempts for failed requests.

Default: 10

pulsora.init({
  apiToken: 'your-token',
  maxRetries: 5, // Reduce retries for faster failure
});

Retry behavior:

Exponential backoff between attempts
Respects Retry-After headers
Stops after max attempts reached

retryBackoff (optional)#

Initial delay in milliseconds before first retry attempt.

Default: 1000 (1 second)

pulsora.init({
  apiToken: 'your-token',
  retryBackoff: 2000, // Start with 2 second delay
});

Backoff progression:

1st retry: retryBackoff ms
2nd retry: retryBackoff * 2 ms
3rd retry: retryBackoff * 4 ms
And so on...

Environment-Based Configuration#

Using Environment Variables#

const pulsora = new Pulsora();
pulsora.init({
  apiToken: process.env.NEXT_PUBLIC_PULSORA_TOKEN,
  debug: process.env.NODE_ENV === 'development',
  endpoint: process.env.PULSORA_ENDPOINT,
});

Environment-Specific Setup#

const isDevelopment = process.env.NODE_ENV === 'development';
const isStaging = process.env.NODE_ENV === 'staging';

const config = {
  apiToken: process.env.PULSORA_TOKEN,
  debug: isDevelopment,
  endpoint: isStaging ? 'https://staging.pulsora.co/ingest' : undefined,
  maxRetries: isDevelopment ? 3 : 10,
};

pulsora.init(config);

CDN Configuration#

When using the CDN version, configure via data attributes:

<script
  async
  src="https://cdn.pulsora.co/v1/pulsora.min.js"
  data-token="your-api-token"
  data-endpoint="https://custom.endpoint.com/ingest"
  data-auto-pageviews="true"
  data-debug="false"
  data-max-retries="10"
  data-retry-backoff="1000"
></script>

Dynamic CDN Configuration#

<script>
  // Configure before script loads
  window.pulsoraConfig = {
    apiToken: 'your-token',
    debug: true,
    autoPageviews: false,
  };
</script>
<script async src="https://cdn.pulsora.co/v1/pulsora.min.js"></script>

Configuration Patterns#

Minimal Configuration#

For most use cases, only the API token is needed:

pulsora.init({ apiToken: 'your-token' });

Development Configuration#

Enhanced debugging and faster failure for development:

pulsora.init({
  apiToken: 'pub_token',
  debug: true,
  maxRetries: 3,
  retryBackoff: 500,
  endpoint: 'http://localhost:8000/api/ingest',
});

Production Configuration#

Optimized for reliability and performance:

pulsora.init({
  apiToken: 'pub_token',
  debug: false,
  maxRetries: 10,
  retryBackoff: 1000,
});

Privacy-Focused Configuration#

Maximum privacy with manual control:

pulsora.init({
  apiToken: 'your-token',
  autoPageviews: false, // Manual control over tracking
});

// Only track after user consent
if (userHasConsented()) {
  pulsora.pageview();
}

Proxy Configuration#

Using a Custom Domain#

Route analytics through your own domain to avoid ad blockers:

Set up a proxy endpoint on your server:

// Express.js example
app.post('/analytics/ingest', async (req, res) => {
  const response = await fetch('https://pulsora.co/api/ingest', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Forwarded-For': req.ip,
    },
    body: JSON.stringify(req.body),
  });

  res.status(response.status).json(await response.json());
});

Configure Pulsora to use your endpoint:

pulsora.init({
  apiToken: 'your-token',
  endpoint: 'https://yourdomain.com/analytics/ingest',
});

Using Cloudflare Workers#

// Cloudflare Worker script
addEventListener('fetch', (event) => {
  event.respondWith(handleRequest(event.request));
});

async function handleRequest(request) {
  const url = new URL(request.url);

  if (url.pathname === '/analytics/ingest') {
    const newRequest = new Request('https://pulsora.co/api/ingest', {
      method: request.method,
      headers: request.headers,
      body: request.body,
    });

    return fetch(newRequest);
  }

  return new Response('Not Found', { status: 404 });
}

Validation#

Checking Configuration#

// Check if initialized
if (!pulsora.isInitialized()) {
  console.error('Pulsora not initialized');
}

// Validate token format
const token = 'pub_abc123';
if (!token.startsWith('pub_')) {
  console.error('Invalid token format - use public tokens only');
}

Debug Mode Validation#

Enable debug mode to validate your configuration:

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

// Check console for:
// ✓ Pulsora initialized with config: {...}
// ✓ Fingerprint generated: fp_xxx
// ✓ Session started: session_xxx

Configuration Best Practices#

1. Use Environment Variables#

// Good
pulsora.init({
  apiToken: process.env.NEXT_PUBLIC_PULSORA_TOKEN,
});

// Bad - hardcoded token
pulsora.init({
  apiToken: 'pub_hardcoded_token',
});

2. Configure Once#

Initialize Pulsora once at app startup:

// Good - single initialization
const pulsora = new Pulsora();
pulsora.init({ apiToken: 'token' });
export default pulsora;

// Bad - multiple initializations
function trackEvent() {
  const pulsora = new Pulsora();
  pulsora.init({ apiToken: 'token' });
  pulsora.event('click');
}

3. Handle Initialization Errors#

try {
  pulsora.init({ apiToken: 'your-token' });
} catch (error) {
  console.error('Failed to initialize Pulsora:', error);
  // Fallback behavior or error reporting
}

4. Test Configuration#

// Development helper
function testPulsoraConfig() {
  const pulsora = new Pulsora();
  pulsora.init({
    apiToken: 'your-token',
    debug: true,
  });

  // Test tracking
  pulsora.event('test_event', { test: true });

  console.log('Check Network tab for requests to:', pulsora.config.endpoint);
}

Troubleshooting Configuration#

Common Issues#

"Invalid API token"

Ensure you're using a public token (starts with pub_)
Check for typos or extra spaces
Verify token in Pulsora dashboard

"Events not tracking"

Enable debug mode to see detailed logs
Check browser console for errors
Verify initialization completed

"Network errors"

Check endpoint URL is correct
Verify no CORS issues with custom endpoints
Look for failed requests in Network tab

Configuration Checklist#

API token starts with pub_
Token is from correct environment (test/live)
Debug mode disabled in production
Custom endpoint URL is valid (if used)
Environment variables are set correctly
Initialization happens before tracking