← Back to DataPulse

DataPulse Tracking Script Integration

Complete guide to implementing analytics tracking with push notifications

Getting Started

DataPulse provides a lightweight tracking script that sends real-time push notifications to your phone when important events happen on your website. The script handles all analytics automatically while giving you full control over user event tracking.

Installation

Add the DataPulse tracking script to your website. Place this code in your HTML <head> section or before the closing </body> tag:

HTML 
<script src="https://thedatapulseapp.com/api/tracking.js?website-id=your-website-id" data-website-id="your-website-id"></script>
ℹ️
Get Your Website ID: Find your unique website ID in the DataPulse iOS app under Settings → Website Settings → Tracking Code.

How It Works

Once installed, the tracking script automatically:

  • Initializes tracking - Creates anonymous visitor and session management
  • Tracks page views - Records every page visit with load times and scroll depth
  • Sets up automatic events - Based on your configuration in the iOS app
  • Respects privacy - Honors Do Not Track settings and user preferences
  • Sends notifications - Triggers real-time push alerts to your phone
⚠️
Important: User events (signup, login, logout, deletion) are NEVER called automatically. You must manually trigger these events in your application code when they occur.

Automatic Event Tracking

DataPulse automatically tracks these events based on your configuration in the iOS app. No additional code is required - events are detected and sent automatically when they occur.

Page Views

Page views are always tracked automatically on every page load. The script captures:

  • Page URL and title - Full URL path and document title
  • Referrer information - Where the visitor came from
  • Load time - How long the page took to fully load
  • Session context - Connected to visitor session data

Scroll Depth Tracking

Scroll depth is automatically tracked in real-time using milestone-based detection:

  • 25% milestone - When user scrolls 25% down the page
  • 50% milestone - When user scrolls 50% down the page
  • 75% milestone - When user scrolls 75% down the page
  • 100% milestone - When user reaches the bottom
📊
Real-time Tracking: Scroll depth data is sent immediately when milestones are reached, ensuring accurate analytics even if users navigate away quickly.

Button Clicks

Automatically detects and tracks clicks on buttons if enabled in your iOS app configuration:

  • <button> elements
  • <input type="button"> and <input type="submit"> elements
  • Elements with role="button" attribute
  • Links styled as buttons (with .btn or .button classes)

Captured data includes button text, ID, CSS classes, and page context.

Form Submissions

Automatically captures form submission events if enabled in your configuration:

  • Form identification - Form ID, name, and CSS classes
  • Form attributes - Action URL and HTTP method
  • Field count - Number of input fields in the form
  • Submission context - Page URL where form was submitted
🔒
Privacy: DataPulse does NOT capture form field values or sensitive user input - only form metadata for analytics.

Manual Event Tracking

User events are NEVER called automatically. You must manually trigger these functions in your application code when user lifecycle events occur. This gives you complete control over when and how user actions are tracked.

⚠️
Manual Triggering Required: User signup, login, logout, and deletion events will only fire when YOU explicitly call the tracking functions in your code.

Track User Signup

Call this method when a new user successfully creates an account:

JavaScript 
// After successful user registration
window.datapulse.trackSignup({
    user_id: '12345',
    email: 'user@example.com',
    username: 'johndoe',
    plan: 'premium',
    source: 'homepage'
});

Parameters: Pass any user data you want to include in the signup notification. All parameters are optional.

Track User Login

Call this method when a user successfully logs into their account:

JavaScript 
// After successful login
window.datapulse.trackLogin({
    user_id: '12345',
    email: 'user@example.com',
    login_method: 'email',
    remember_me: true
});

Track User Logout

Call this method when a user logs out of their account:

JavaScript 
// When user logs out
window.datapulse.trackLogout({
    user_id: '12345',
    logout_method: 'manual'
});

Track User Deletion

Call this method when a user deletes their account:

JavaScript 
// When user deletes account
window.datapulse.trackUserDeletion({
    user_id: '12345',
    deletion_reason: 'privacy_concerns',
    account_age_days: 30
});
📱
Push Notifications: These manual events trigger immediate push notifications to your phone, but only if the corresponding event is enabled in your iOS app configuration.

Integration Examples

Basic Setup Example

Complete example showing how to integrate DataPulse into a basic website:

HTML 
<!DOCTYPE html>
<html>
<head>
    <title>My Website</title>
    <!-- DataPulse tracking script -->
    <script src="https://thedatapulseapp.com/api/tracking.js" data-website-id="your-website-id"></script>
</head>
<body>
    <h1>Welcome to My Website</h1>
    
    <!-- Automatic tracking: button clicks, forms, links work automatically -->
    <button onclick="handleSignup()">Sign Up</button>
    <form onsubmit="handleLogin()">...</form>
    <a href="/pricing">View Pricing</a>
    
    <script>
        // Manual tracking: call when user events occur
        function handleSignup() {
            // Your signup logic here...
            
            // Track the signup manually
            window.datapulse.trackSignup({
                user_id: newUserId,
                email: userEmail,
                source: 'homepage'
            });
        }
    </script>
</body>
</html>

User Event Integration

Example of integrating user tracking with a typical authentication system:

JavaScript 
// Integration with authentication system
class AuthManager {
    async signupUser(userData) {
        try {
            // Your signup API call
            const result = await fetch('/api/signup', {
                method: 'POST',
                body: JSON.stringify(userData)
            });
            
            if (result.ok) {
                const user = await result.json();
                
                // Track successful signup
                window.datapulse.trackSignup({
                    user_id: user.id,
                    email: user.email,
                    plan: user.subscription_plan
                });
                
                return user;
            }
        } catch (error) {
            console.error('Signup failed:', error);
        }
    }
    
    async loginUser(credentials) {
        try {
            const result = await fetch('/api/login', {
                method: 'POST',
                body: JSON.stringify(credentials)
            });
            
            if (result.ok) {
                const user = await result.json();
                
                // Track successful login
                window.datapulse.trackLogin({
                    user_id: user.id,
                    login_method: 'email'
                });
                
                return user;
            }
        } catch (error) {
            console.error('Login failed:', error);
        }
    }
    
    logoutUser() {
        // Your logout logic
        this.clearSession();
        
        // Track logout
        window.datapulse.trackLogout({
            user_id: this.currentUserId
        });
    }
}

React Integration

Example of using DataPulse in a React application:

JavaScript 
// React component with DataPulse integration
import { useEffect } from 'react';

function SignupForm() {
    const handleSignup = async (formData) => {
        try {
            // Your signup logic
            const response = await signupAPI(formData);
            
            if (response.success) {
                // Track signup with DataPulse
                if (window.datapulse) {
                    window.datapulse.trackSignup({
                        user_id: response.user.id,
                        email: response.user.email,
                        source: 'signup_form'
                    });
                }
                
                // Redirect or show success
                navigate('/dashboard');
            }
        } catch (error) {
            console.error('Signup error:', error);
        }
    };
    
    return (
        <form onSubmit={handleSignup}>
            {/* Your form fields */}
            <button type="submit">Sign Up</button>
        </form>
    );
}

API Security & Restrictions

🚨
CRITICAL WARNING: DataPulse API endpoints are strictly internal and protected by advanced security measures. DO NOT attempt to call API endpoints directly from your code.

API Usage Restrictions

DataPulse API endpoints are designed exclusively for internal use by the tracking script. Direct API access is blocked for security reasons:

  • Domain validation - All requests must originate from your registered domain
  • Request origin verification - Origin and Referer headers are strictly validated
  • Script-only access - Only requests from tracking.js are accepted
  • Cross-domain protection - Requests from unauthorized domains are blocked
⛔
Blocked Actions: Direct API calls via fetch(), XMLHttpRequest, cURL, Postman, or any method other than the official tracking script will be rejected with 403 Forbidden errors.

Domain Validation

DataPulse validates that all tracking requests originate from your registered domain:

  • Exact domain match - yoursite.com ✅
  • Subdomain support - blog.yoursite.com ✅
  • www. variations - www.yoursite.com ✅
  • Cross-domain blocked - malicious-site.com ❌

This ensures your analytics data can only be sent from your actual website, preventing abuse and unauthorized tracking.

Security Features

DataPulse includes enterprise-level security protections:

  • JSON injection protection - Prevents malicious payloads
  • Rate limiting safeguards - Protects against abuse
  • Input validation - All data is sanitized and validated
  • Session integrity - Cryptographically secure session management
  • Privacy compliance - Respects Do Not Track and privacy settings
🔒
Secure by Design: Use only the provided tracking.js script for all DataPulse integration. This ensures maximum security and compatibility with our protection systems.

Troubleshooting

Debugging

If tracking isn't working as expected, check these common issues:

JavaScript 
// Check if DataPulse is loaded
console.log('DataPulse loaded:', typeof window.datapulse !== 'undefined');

// Check current configuration
if (window.datapulse) {
    console.log('Website ID:', window.datapulse.websiteId);
    console.log('Selected events:', window.datapulse.selectedEvents);
    console.log('Respects DNT:', window.datapulse.respectDnt);
}

// Test manual tracking
window.datapulse.trackSignup({ test: true });

Common Issues

Tracking script not loading

  • Verify the script URL is correct: https://thedatapulseapp.com/api/tracking.js
  • Check that data-website-id attribute is set correctly
  • Ensure no ad blockers are preventing the script from loading
  • Check browser console for any error messages

Manual events not triggering

  • Verify the event is enabled in your iOS app configuration
  • Check that window.datapulse is available before calling tracking functions
  • Ensure you're calling the correct function names (trackSignup, trackLogin, etc.)
  • Verify your website domain matches the registered domain in DataPulse

No push notifications received

  • Check notification settings in the iOS app (Settings → Notifications)
  • Verify the specific event type is enabled for notifications
  • Ensure push notifications are enabled in iOS Settings for DataPulse
  • Check that tracking events are actually being sent (use browser dev tools)

Automatic events not working

  • Verify the event types are enabled in your iOS app event configuration
  • Check that the website verification is complete
  • Ensure elements have proper HTML structure (buttons, forms, links)
  • Verify Do Not Track is not enabled if you have DNT respect turned on

403 Forbidden errors

  • This indicates domain validation failure
  • Verify your website domain exactly matches what's registered in DataPulse
  • Check that you're not making direct API calls instead of using tracking.js
  • Ensure the script is loaded from the same domain as your website
💡
Need Help? If you're still experiencing issues, check your analytics dashboard in the DataPulse iOS app to see if events are being received, or contact support through the app.