← Back to home

Integration guide

Add the clickpulse tracker to your website in minutes. Pageviews are tracked automatically; use the JavaScript API for custom events.

Getting started

Before adding the tracker to your site, you need to create an account and add your website. Your tracking snippet (with your unique site ID) is generated when you add a website.

Create an account — Sign up for free if you haven't already.
Add your website — Go to Dashboard, open Websites in the sidebar, and click Add Website. Enter your domain (e.g. example.com).
Get your tracking snippet — On the Websites page, click View tracking code on your website's card. You'll see the full script with your unique site ID—copy it and you're ready to add it to your site.

Once you have your snippet, add it to your website as described below.

Add the script

Add your tracking snippet to the <head> or <body> of every page you want to track. If you copied it from the dashboard, your site ID is already included.

<script defer data-site="your-site-id" data-api="https://clickpulse.sh/api/event" src="https://clickpulse.sh/js/tracker-v2.js"></script>

That's it. Pageviews are sent automatically. For custom events (button clicks, form submissions, etc.), use clickPulse.track().

How it works

Pageviews — Sent automatically when the script loads (or when the page becomes visible after prerender).

Custom events — Call clickPulse.track(name, data) anywhere in your code.

Parameter	Description
t	Site ID (from data-site)
u	Full URL
p	Pathname
d	Device type (mobile, tablet, desktop)
r	External referrer (if different domain)
e	Event name (custom events only)
ed	Event data (custom events only)

Vanilla JavaScript

Use clickPulse.track() for custom events. Pass a string or object as the second argument.

// Simple event (no data)
clickPulse.track('button_clicked');

// Event with object data
clickPulse.track('purchase', {
  productId: 'prod_123',
  amount: 49.99,
  currency: 'USD'
});

// Form submission
document.querySelector('#contact-form').addEventListener('submit', function() {
  clickPulse.track('form_submitted', { form: 'contact' });
});

React

Create a custom hook and use it in your components.

1. Create the hook

// hooks/useAnalytics.ts
import { useCallback } from 'react';

declare global {
  interface Window {
    clickPulse?: {
      track: (name: string, data?: string | Record<string, unknown>) => void;
    };
  }
}

export function useAnalytics() {
  const track = useCallback((eventName: string, eventData?: string | Record<string, unknown>) => {
    window.clickPulse?.track(eventName, eventData);
  }, []);

  return { track };
}

2. Use in components

function CtaButton() {
  const { track } = useAnalytics();

  return (
    <button onClick={() => track('cta_clicked', { location: 'hero' })}>
      Get Started
    </button>
  );
}

React + Inertia.js

Add the tracker to your Blade layout, then use the Inertia navigate event to track SPA page visits.

1. Add tracker to app.blade.php

<script
  src="https://clickpulse.sh/js/tracker-v2.js"
  data-site="{{ $analyticsSiteId ?? 'your-site-id' }}"
  data-api="https://clickpulse.sh/api/event"
></script>
@inertia

2. Track Inertia navigations (app.tsx)

import { router } from '@inertiajs/react'

router.on('navigate', (event) => {
  window.clickPulse?.track('page_view', { path: event.detail.page.url })
})

Vue.js

Use a composable for tracking in Vue 3.

1. Create the composable

// composables/useAnalytics.ts
export function useAnalytics() {
  const track = (eventName: string, eventData?: string | Record<string, unknown>) => {
    window.clickPulse?.track(eventName, eventData);
  };
  return { track };
}

2. Use in components

<script setup>
import { useAnalytics } from '@/composables/useAnalytics'

const { track } = useAnalytics()
</script>

<template>
  <button @click="track('cta_clicked', { location: 'hero' })">
    Get Started
  </button>
</template>

Vue.js + Inertia.js

Add the tracker to your Blade layout, then use the Inertia navigate event to track SPA page visits. Same as React + Inertia: add the script to app.blade.php and use router.on('navigate', ...) in app.ts.

Understanding your metrics

How we track activity — We record each page load with a timestamp. We group page loads by visitor (IP + browser) and date. Within that group, we split the sequence into visits using a 30-minute timeout.

Session timeout (30 minutes) — If a visitor loads a page, then loads another page more than 30 minutes later, we treat that as a new visit. This avoids counting idle time (e.g. a tab left open while the user is away) as time on site.

Example:

10:00 — homepage
10:02 — /about
15:45 — /contact (gap > 30 min)
15:50 — /pricing

Result: 2 visits. Visit 1: 2 min (10:00–10:02). Visit 2: 5 min (15:45–15:50). Avg visit duration = (2 + 5) / 2 = 3.5 min.

Metrics explained:

Metric	Definition
Total views	Number of page loads in the period
Unique visitors	Distinct visitors (IP + browser) per day
Sessions	Number of visits
Bounce rate	% of visits with only 1 page view (visitor left after one page)
Pages per session	Total views ÷ number of visits
Avg. visit duration	Sum of visit durations ÷ number of visits. Duration per visit = time between first and last page load in that visit. Single-page visits = 0 seconds
Entry page	First page of each visit
Exit page	Last page of each visit

Single-page visits — A visit with only one page view has 0 seconds duration and counts as a bounce.

Chart markers

What are chart markers? — Annotations on the main dashboard chart to correlate traffic changes with events (campaign launch, viral post, etc.). Each marker appears as a red dot at a specific date.

Adding a marker — Click Add Marker in the chart header; pick a date (dates with existing markers are disabled); enter a description; submit.

Viewing markers — Red dots appear below the X-axis at their dates. Hover to see the description in a tooltip.

Editing or deleting — Click a marker dot to open the edit dialog; change date or description, or delete.

Constraints — One marker per date per website.

Quick reference

Scenario	Approach
Initial page load	Automatic pageview from tracker script
SPA / Inertia navigation	`router.on('navigate', ...)`
Custom events	`clickPulse.track(name, data)`
Forms	Call track() before submitting
Links	Use onClick / @click with track()

Ready to get started?

Add your website and copy your tracking snippet from the dashboard.

Get started free