@pavekit/sdk

v1.0.10

Published

6 months ago

PaveKit JavaScript SDK for automated user onboarding detection

0High
0Medium
0Low

pavekit

onboarding email campaigns user-tracking saas automation analytics conversion

PaveKit JavaScript SDK

Privacy-compliant user onboarding detection for automated email campaigns.

The PaveKit SDK automatically detects user signups and activity on your website to trigger personalized onboarding email campaigns. Built with privacy-first principles and GDPR compliance.

Features

Automatic Signup Detection - Detects form submissions and OAuth completions
Privacy-First - GDPR compliant with user consent management
Security Focused - Never captures passwords or sensitive data
Lightweight - Under 15KB gzipped
Cross-Browser - Works in all modern browsers
Mobile Friendly - Optimized for mobile devices
Easy Integration - One script tag to get started

Quick Start

1. Script Tag Integration (Recommended)

Add the SDK to your website's <head> section:

<script src="https://cdn.pavekit.com/sdk/pavekit.min.js"
        data-key="your-api-key"
        data-detect="signups,activity">
</script>

That's it! The SDK will automatically:

Detect user signups on your forms
Track OAuth authentication completions
Monitor user activity (with consent)
Send data to trigger your email campaigns

2. NPM Installation

npm install @pavekit/sdk

import PaveKitSDK from '@pavekit/sdk';

const sdk = new PaveKitSDK();
await sdk.init({
  apiKey: 'your-api-key',
  detect: ['signups', 'activity', 'oauth']
});

Configuration Options

Script Tag Attributes

| Attribute | Default | Description | |-----------|---------|-------------| | data-key | required | Your PaveKit API key | | data-detect | "signups,activity" | Detection features to enable | | data-base-url | Production URL | API base URL (for development) | | data-debug | false | Enable debug logging | | data-privacy | "gdpr-compliant" | Privacy compliance mode | | data-consent-banner | true | Show consent banner |

JavaScript Configuration

const config = {
  apiKey: 'your-api-key',              // Required: Your API key
  baseURL: 'https://api.pavekit.com',  // API endpoint
  detect: ['signups', 'oauth', 'activity'], // Features to detect
  debug: false,                         // Debug mode
  privacy: 'gdpr-compliant',           // Privacy mode
  consentBanner: true,                 // Show consent banner
  autoCleanup: true                    // Clean sensitive URL params
};

await sdk.init(config);

Detection Features

Signup Detection (signups)

Automatically detects when users complete signup forms:

Email field detection - Captures email addresses securely
Password filtering - Never captures passwords or sensitive data
Smart form recognition - Distinguishes signup from login forms
Security validation - Validates all data before capture

What gets detected:

Registration forms with email + password
Newsletter signups (if configured)
Account creation forms
Trial signup forms

What gets filtered out:

Login forms
Password reset forms
Contact forms
Search forms

OAuth Detection (oauth)

Detects OAuth authentication completions:

Provider detection - Google, GitHub, Microsoft, Facebook, etc.
Token-safe - Never accesses OAuth tokens or secrets
Real-time detection - Catches OAuth redirects immediately
URL cleanup - Removes sensitive parameters from URLs

Supported OAuth providers:

Google (oauth_google)
GitHub (oauth_github)
Microsoft (oauth_microsoft)
Facebook (oauth_facebook)
Twitter (oauth_twitter)
Custom OAuth providers

Activity Tracking (activity)

Privacy-compliant user engagement tracking:

Time on page - Measures active engagement time
Scroll depth - Tracks how far users scroll
Click tracking - Counts safe interactions only
Visibility detection - Respects page visibility
Consent required - Only tracks with user permission

Activity metrics:

Session duration
Active time (excludes idle time)
Scroll percentage
Safe click count
Page views

Privacy and Security

GDPR Compliance

The SDK is built for privacy compliance:

// Check consent status
const consent = sdk.getConsentStatus();
console.log(consent.hasConsent);     // User has given consent
console.log(consent.isOptedOut);     // User has opted out
console.log(consent.doNotTrack);     // Browser DNT setting

// Request consent manually
const hasConsent = await sdk.requestConsent();

// Opt out completely
sdk.optOut();

// Delete all user data
sdk.deleteUserData();

Security Features

No sensitive data - Never captures passwords, tokens, or PII
Field filtering - Automatically filters sensitive form fields
Input validation - Validates and sanitizes all captured data
Secure transmission - HTTPS-only API communication
Data minimization - Captures only necessary information

Data Protection

// What we NEVER capture:
// - Passwords
// - Credit card numbers
// - OAuth tokens
// - API keys
// - Social security numbers
// - Hidden form fields

// What we DO capture (with consent):
// - Email addresses
// - Names (first/last)
// - Company information
// - Safe form data only

API Reference

SDK Methods

init(config)

Initialize the SDK with configuration:

await sdk.init({
  apiKey: 'your-api-key',
  detect: ['signups', 'activity'],
  debug: true
});

trackSignup(data)

Manually track a signup event:

await sdk.trackSignup({
  email: '[email protected]',
  method: 'manual',
  metadata: {
    source: 'landing-page'
  }
});

updateUser(data)

Update user information such as name. This allows you to personalize onboarding emails with the user's actual name instead of extracting it from their email address.

await sdk.updateUser({
  email: '[email protected]',
  name: 'John Smith'
});

Parameters:

email (required) - User's email address to identify the user
name (optional) - User's display name for email personalization

The name will be used in email templates via the {{user_name}} variable.

trackConversion(data)

Track conversion events to stop email campaigns:

await sdk.trackConversion({
  email: '[email protected]',
  type: 'purchase',
  value: 99.99,
  currency: 'USD'
});

setUserEmail(email)

Set user email for activity tracking:

sdk.setUserEmail('[email protected]');

getStatus()

Get current SDK status:

const status = sdk.getStatus();
console.log(status);
// {
//   version: '1.0.0',
//   initialized: true,
//   detecting: true,
//   hasConsent: true,
//   detectors: { ... }
// }

Privacy Methods

getConsentStatus()

Check privacy consent status:

const consent = sdk.getConsentStatus();
console.log(consent);
// {
//   hasConsent: true,
//   isOptedOut: false,
//   consentTimestamp: '2023-...',
//   doNotTrack: false
// }

optOut() / optIn()

Manage user privacy preferences:

// Opt out of all tracking
sdk.optOut();

// Opt back in (requests consent)
const hasConsent = await sdk.optIn();

Template Variables

When users are tracked by the SDK, their information can be used in email templates. The following variables are available:

| Variable | Description | Source | |----------|-------------|--------| | {{user_email}} | User's email address | Detected from signup form or OAuth | | {{user_name}} | User's display name | Set via updateUser() or extracted from email | | {{signup_date}} | Date when user signed up | Automatic | | {{company_name}} | Your company name | Set in PaveKit Profile settings | | {{discount_code}} | Discount code from template | Template configuration | | {{discount_value}} | Discount percentage | Template configuration | | {{product_name}} | Your product name | Set in PaveKit Profile settings | | {{support_email}} | Your support email | Your account email |

Updating User Name

To personalize emails with the user's actual name (instead of extracting from email), call updateUser() after signup:

// After detecting a signup or getting user info from your backend
await sdk.updateUser({
  email: '[email protected]',
  name: 'John Smith'
});

This is especially useful when:

You have the user's name from an OAuth provider
The user provides their name in a profile form
You want more personalized onboarding emails

Advanced Usage

Custom Event Listeners

Listen for SDK events:

// SDK initialized
window.addEventListener('pavekit-initialized', (e) => {
  console.log('SDK ready:', e.detail.version);
});

// Detection started
window.addEventListener('pavekit-detectionStarted', (e) => {
  console.log('Detecting:', e.detail.detectors);
});

// Consent changed
window.addEventListener('pavekit-consent', (e) => {
  console.log('Consent:', e.detail.type);
});

Manual Detection Control

Control detection manually:

// Start detection
sdk.startDetection();

// Stop detection
sdk.stopDetection();

// Update configuration
sdk.updateConfig({
  detect: ['signups'], // Only detect signups
  debug: true
});

Custom Privacy Settings

Customize privacy behavior:

await sdk.init({
  apiKey: 'your-api-key',
  consentBanner: true,
  privacy: 'gdpr-compliant'
});

// Custom consent request
const hasConsent = await sdk.privacyManager.requestConsent({
  message: 'We use cookies to improve your experience.',
  privacyUrl: '/privacy-policy',
  timeout: 30000
});

Debug Mode

Enable debugging for development:

// Via config
await sdk.init({
  apiKey: 'your-api-key',
  debug: true
});

// Get debug information
const debugInfo = sdk.getDebugInfo();
console.log(debugInfo);

Integration Examples

React Integration

import { useEffect } from 'react';
import PaveKitSDK from '@pavekit/sdk';

function App() {
  useEffect(() => {
    const initPaveKit = async () => {
      const sdk = new PaveKitSDK();
      await sdk.init({
        apiKey: process.env.REACT_APP_PAVEKIT_KEY,
        detect: ['signups', 'activity']
      });
      
      // Make SDK available globally
      window.pavekit = sdk;
    };
    
    initPaveKit();
  }, []);

  return <div>Your app content</div>;
}

Vue Integration

<script>
import PaveKitSDK from '@pavekit/sdk';

export default {
  async mounted() {
    const sdk = new PaveKitSDK();
    await sdk.init({
      apiKey: process.env.VUE_APP_PAVEKIT_KEY,
      detect: ['signups', 'oauth', 'activity']
    });
    
    this.$pavekit = sdk;
  }
}
</script>

Next.js Integration

// pages/_app.js
import { useEffect } from 'react';

function MyApp({ Component, pageProps }) {
  useEffect(() => {
    // Load SDK after hydration
    if (typeof window !== 'undefined') {
      import('@pavekit/sdk').then(async ({ default: PaveKitSDK }) => {
        const sdk = new PaveKitSDK();
        await sdk.init({
          apiKey: process.env.NEXT_PUBLIC_PAVEKIT_KEY,
          detect: ['signups', 'activity']
        });
      });
    }
  }, []);

  return <Component {...pageProps} />;
}

Capturing User Name from OAuth

When using OAuth providers like Google, you often receive the user's name. Pass it to PaveKit:

// After OAuth callback
async function handleOAuthSuccess(oauthUser) {
  // Track the signup
  await window.pavekit.trackSignup({
    email: oauthUser.email,
    method: 'oauth_google'
  });
  
  // Update with the user's actual name from OAuth
  if (oauthUser.name) {
    await window.pavekit.updateUser({
      email: oauthUser.email,
      name: oauthUser.name
    });
  }
}

E-commerce Integration

Track purchases to stop onboarding campaigns:

// After successful purchase
await sdk.trackConversion({
  email: customerEmail,
  type: 'purchase',
  value: orderTotal,
  currency: 'USD',
  metadata: {
    orderId: order.id,
    products: order.items.map(item => item.name)
  }
});

Troubleshooting

Common Issues

SDK not initializing:

// Check API key is set
const script = document.querySelector('script[src*="pavekit"]');
console.log(script.dataset.key); // Should show your API key

// Check console for errors
sdk.getDebugInfo(); // Shows detailed status

Forms not being detected:

// Check detector status
const status = sdk.getStatus();
console.log(status.detectors.form); // Should show isActive: true

// Check form structure
const forms = sdk.detectors.form.getDetectedForms();
console.log(forms); // Shows detected forms

Privacy consent issues:

// Check consent status
const consent = sdk.getConsentStatus();
console.log(consent);

// Force consent for testing (development only)
sdk.privacyManager.grantConsent('explicit');

Debug Mode

Enable debug mode for detailed logging:

<script src="https://cdn.pavekit.com/sdk/pavekit.min.js"
        data-key="your-api-key"
        data-debug="true">
</script>

Browser Support

Supported browsers:

Chrome 60+
Firefox 55+
Safari 12+
Edge 79+

Required features:

fetch() API
Promise support
addEventListener()
querySelector()

Testing

Test Page

Create a test page to verify SDK functionality:

<!DOCTYPE html>
<html>
<head>
    <script src="https://cdn.pavekit.com/sdk/pavekit.min.js"
            data-key="your-test-api-key"
            data-debug="true">
    </script>
</head>
<body>
    <h1>SDK Test Page</h1>
    
    <!-- Test signup form -->
    <form id="signup-form" action="/signup" method="post">
        <input type="text" name="name" placeholder="Name">
        <input type="email" name="email" placeholder="Email" required>
        <input type="password" name="password" placeholder="Password" required>
        <button type="submit">Sign Up</button>
    </form>
    
    <script>
        // Check SDK status
        setTimeout(() => {
            if (window.PaveKit) {
                console.log('SDK Status:', window.PaveKit.getStatus());
            }
        }, 1000);
        
        // Test updating user name after form submission
        document.getElementById('signup-form').addEventListener('submit', async (e) => {
            const formData = new FormData(e.target);
            const name = formData.get('name');
            const email = formData.get('email');
            
            if (name && email && window.PaveKit) {
                await window.PaveKit.updateUser({ email, name });
            }
        });
    </script>
</body>
</html>

Manual Testing

Test SDK functions in browser console:

// Check if SDK loaded
console.log(window.PaveKit);

// Get status
window.PaveKit.getStatus();

// Test manual tracking
await window.PaveKit.trackSignup({
  email: '[email protected]',
  method: 'manual'
});

// Test updating user info
await window.PaveKit.updateUser({
  email: '[email protected]',
  name: 'Test User'
});

// Check activity stats
window.PaveKit.detectors.activity.getActivityStats();

SDK Endpoints

The SDK communicates with the following backend endpoints:

| Endpoint | Method | Description | |----------|--------|-------------| | /api/onboarding/sdk/signup | POST | Register a new user signup | | /api/onboarding/sdk/activity | POST | Track user activity heartbeat | | /api/onboarding/sdk/conversion | POST | Track conversion events | | /api/onboarding/sdk/user-info | POST | Update user information (name) | | /api/onboarding/sdk/validate | GET | Validate API key |

License

MIT License - see LICENSE file for details.

PaveKit - Automated User Onboarding

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

PaveKit JavaScript SDK

Features

Quick Start

1. Script Tag Integration (Recommended)

2. NPM Installation

Configuration Options

Script Tag Attributes

JavaScript Configuration

Detection Features

Signup Detection (signups)

OAuth Detection (oauth)

Activity Tracking (activity)

Privacy and Security

GDPR Compliance

Security Features

Data Protection

API Reference

SDK Methods

init(config)

trackSignup(data)

updateUser(data)

trackConversion(data)

setUserEmail(email)

getStatus()

Privacy Methods

getConsentStatus()

optOut() / optIn()

Template Variables

Updating User Name

Advanced Usage

Custom Event Listeners

Manual Detection Control

Custom Privacy Settings

Debug Mode

Integration Examples

React Integration

Vue Integration

Next.js Integration

Capturing User Name from OAuth

E-commerce Integration

Troubleshooting

Common Issues

Debug Mode

Browser Support

Testing

Test Page

Manual Testing

SDK Endpoints

Links

License