Send Your First Event

Learn how to send events to PULSE

Send Your First Event

Get started with event tracking in just a few minutes.

Understanding Events

Events are the core of PULSE analytics. Each event represents a user action:

{
  "site_id": "site_abc123",
  "event_type": "page_view",
  "timestamp": 1703001234567,
  "session_id": "session_xyz789",
  "user_id": "user_123",
  "url": "https://example.com/products",
  "referrer": "https://google.com",
  "device_type": "desktop",
  "country": "US"
}

Event Fields

Method 1: REST API

Send an event via HTTP:

curl -X POST https://your-api.example.com/collect \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "site_id": "site_abc123",
    "event_type": "page_view",
    "timestamp": '$(date +%s000)',
    "session_id": "session_123",
    "url": "https://example.com",
    "device_type": "desktop"
  }'

Method 2: JavaScript SDK

Use the JavaScript SDK in your web application:

<!-- Include the tracker script -->
<script src="https://your-api.example.com/tracker.js"></script>

<!-- Initialize PULSE -->
<script>
  window.PULSE.init({
    siteId: 'site_abc123',
    apiKey: 'YOUR_API_KEY',
    endpoint: 'https://your-api.example.com'
  })

  // Track page view
  window.PULSE.trackPageView({
    url: window.location.href,
    referrer: document.referrer,
    deviceType: 'desktop'
  })

  // Track custom event
  window.PULSE.trackEvent('user_signup', {
    userId: 'user_123',
    plan: 'premium'
  })
</script>

Method 3: TypeScript/Node.js SDK

import { PulseClient } from '@pulse/sdk'

const pulse = new PulseClient({
  siteId: 'site_abc123',
  apiKey: 'YOUR_API_KEY',
  endpoint: 'https://your-api.example.com'
})

// Send event
await pulse.trackEvent({
  eventType: 'page_view',
  sessionId: 'session_123',
  url: '/products',
  deviceType: 'desktop'
})

Event Types

Common event types:

Example: Page View Event

const event = {
  site_id: 'site_abc123',
  event_type: 'page_view',
  timestamp: Date.now(),
  session_id: generateSessionId(),
  url: window.location.href,
  referrer: document.referrer,
  device_type: detectDeviceType(),
  country: getUserCountry()
}

await fetch('https://your-api.example.com/collect', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${apiKey}`
  },
  body: JSON.stringify(event)
})

Example: Custom Event

const event = {
  site_id: 'site_abc123',
  event_type: 'user_signup',
  timestamp: Date.now(),
  session_id: sessionId,
  user_id: userId,
  url: window.location.href
}

await pulse.trackEvent(event)

Batch Events

For better performance, batch events:

const events = [
  { event_type: 'page_view', ... },
  { event_type: 'click', ... },
  { event_type: 'form_submit', ... }
]

// Send batch
await fetch('https://your-api.example.com/collect/batch', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${apiKey}`
  },
  body: JSON.stringify({ events })
})

Query Your Events

After sending events, query them:

curl "https://your-api.example.com/api/v1/stats?site_id=site_abc123&metric=event_count" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "data": {
    "metric": "event_count",
    "value": 42,
    "period": "24h"
  }
}

Troubleshooting

Events Not Being Recorded?

1. Check the site_id matches your registered site
2. Verify API key is correct
3. Check timestamp is recent (within last 30 days)
4. Verify network request succeeds (HTTP 200)

Query Returns Zero Events?

1. Wait 5-10 seconds for events to be processed
2. Check time range in query
3. Verify site_id in query matches event site_id

Rate Limiting?

PULSE implements rate limiting to prevent abuse:

{
  "success": false,
  "error": "Rate limit exceeded",
  "status": 429
}

Wait 60 seconds and retry.

Next Steps

• Event Ingestion API — Full API reference
• Analytics Queries — Query your data
• Architecture — How events flow through PULSE