consent-sdk-aera

v0.0.0

Published

6 months ago

A production-ready JavaScript Consent SDK for multi-tenant SaaS platforms, fully compliant with India's Digital Personal Data Protection Act (DPDP). Supports both device-level (anonymous) and user-level (PII) consent tracking with comprehensive cookie and

0High
0Medium
0Low

sujeethmemane

Consent SDK - DPDP Act Compliant

Features

🛡️ DPDP Act Compliant - Built to comply with India's data protection regulations
🎯 Dual Consent Modes - Cookie mode for anonymous users, PII mode for authenticated users
🔍 Automatic Scanning - Detects and categorizes cookies and localStorage items
📊 Comprehensive Reporting - Detailed reports for compliance and audit purposes
🎨 Customizable UI - Beautiful, responsive consent banners with custom styling
🏢 Multi-tenant Ready - Built for SaaS platforms with tenant isolation
📱 Responsive Design - Works seamlessly across all device sizes
⚡ TypeScript Support - Full TypeScript definitions included

Quick Start

Basic Usage (Vanilla JavaScript)

<!DOCTYPE html>
<html>
<head>
    <title>My Website</title>
</head>
<body>
    <!-- Your content -->
    
    <script src="https://cdn.yourdomain.com/consent-sdk.min.js"></script>
    <script>
        ConsentSDK.init({
            tenantId: 'your-tenant-id',
            scanOnInit: true,
            reportScan: true,
            purposeMap: {
                '_ga': 'analytics',
                '_gid': 'analytics',
                '_fbp': 'marketing',
                'user_preferences': 'functional'
            },
            apiEndpoint: 'https://your-api.com'
        });
    </script>
</body>
</html>

React Integration

import { ConsentSDK } from '@yourorg/consent-sdk';
import { useEffect } from 'react';

function App() {
    useEffect(() => {
        ConsentSDK.init({
            tenantId: 'your-tenant-id',
            userId: user?.id, // Optional - for authenticated users
            scanOnInit: true,
            reportScan: true,
            purposeMap: {
                '_ga': 'analytics',
                '_gid': 'analytics',
                '_fbp': 'marketing',
                'intercom_session': 'marketing',
                'user_preferences': 'functional',
                'shopping_cart': 'functional'
            },
            apiEndpoint: 'https://your-api.com',
            customStyles: {
                primaryColor: '#3B82F6',
                backgroundColor: '#ffffff',
                textColor: '#374151'
            }
        });
    }, [user]);

    return <div>Your App Content</div>;
}

API Reference

ConsentSDK.init(config)

Initialize the SDK with configuration options.

interface ConsentSDKConfig {
    tenantId: string;           // Your tenant identifier
    userId?: string;            // Optional user ID for PII mode
    scanOnInit?: boolean;       // Auto-scan on initialization
    reportScan?: boolean;       // Send scan reports to backend
    purposeMap?: Record<string, string>; // Map keys to consent purposes
    apiEndpoint?: string;       // Your API endpoint
    customStyles?: ConsentBannerStyles; // Custom styling
}

Core Methods

// Get device ID (always available)
const deviceId = ConsentSDK.getDeviceId();

// Get user ID (if set)
const userId = ConsentSDK.getUserId();

// Set user ID (migrates from cookie to PII mode)
await ConsentSDK.setUserId('user_123');

// Get current consent state
const state = ConsentSDK.getConsentState();

// Update specific consent
await ConsentSDK.updateConsent('analytics', true);

// Show consent banner
ConsentSDK.showBanner();

// Hide consent banner
ConsentSDK.hideBanner();

// Perform scan and report
await ConsentSDK.scanAndReport();

// Reset all data
ConsentSDK.reset();

Consent Modes

Cookie Mode (Anonymous)

Triggered when only deviceId is available
Consent tracked against device and tenant
Used for non-PII data (analytics, preferences)
Storage key: consent_device_{tenantId}_{deviceId}

PII Mode (Authenticated)

Triggered when userId is provided
Consent tracked against user and tenant
Used for personal data processing
Storage key: consent_user_{tenantId}_{userId}
Supports migration from Cookie mode

Purpose Categories

The SDK supports the following consent purposes:

Analytics - Website usage analytics and performance monitoring
Marketing - Advertising and promotional content
Functional - Essential website functionality (usually required)
Personalization - Customized user experience
Other - Custom categories defined by your application

Backend Integration

Consent Collection Endpoint

POST /api/consent/collect
{
    "tenantId": "tenant_123",
    "deviceId": "device_abc", // Cookie mode
    "userId": "user_456",     // PII mode
    "purposeId": "analytics",
    "status": true,
    "method": "cookie" | "pii",
    "timestamp": 1234567890
}

Scan Report Endpoint

POST /api/scan/report
{
    "tenantId": "tenant_123",
    "deviceId": "device_abc",
    "userId": "user_456",
    "method": "cookie" | "pii",
    "timestamp": 1234567890,
    "consentState": {
        "analytics": true,
        "marketing": false,
        "functional": true
    },
    "detectedKeys": [
        {
            "name": "_ga",
            "type": "cookie",
            "category": "analytics",
            "consentGranted": true
        }
    ]
}

Customization

Custom Styling

ConsentSDK.init({
    // ... other config
    customStyles: {
        backgroundColor: '#ffffff',
        textColor: '#374151',
        primaryColor: '#3B82F6',
        borderRadius: '12px',
        fontFamily: 'Inter, sans-serif'
    }
});

Purpose Mapping

Define how cookies and localStorage keys map to consent purposes:

const purposeMap = {
    // Google Analytics
    '_ga': 'analytics',
    '_gid': 'analytics',
    '_gat': 'analytics',
    
    // Facebook Pixel
    '_fbp': 'marketing',
    '_fbc': 'marketing',
    
    // Intercom
    'intercom_session': 'marketing',
    
    // Functional
    'user_preferences': 'functional',
    'shopping_cart': 'functional',
    'auth_token': 'functional'
};

DPDP Compliance Features

Granular Consent - Purpose-based consent management
Data Minimization - Only collect necessary consent data
Transparency - Clear descriptions of data usage
User Control - Easy consent withdrawal and modification
Audit Trail - Comprehensive logging and reporting
Data Portability - Export consent preferences
Retention Management - Automatic data cleanup

Browser Support

Chrome 60+
Firefox 55+
Safari 12+
Edge 79+
Mobile browsers with ES6 support

Installation

NPM

npm install @yourorg/consent-sdk

CDN

<script src="https://cdn.yourdomain.com/consent-sdk.min.js"></script>

Development

# Install dependencies
npm install

# Run demo
npm run dev

# Build SDK
npm run build:sdk

# Run tests
npm test

License

MIT License - see LICENSE file for details.

Support

For support and questions:

Documentation: https://docs.yourdomain.com/consent-sdk
Issues: https://github.com/yourorg/consent-sdk/issues
Email: [email protected]