Questera Raw Event SDK

A comprehensive web raw event SDK for tracking user interactions, page views, and custom events with automatic browser and device detection.

Features

• 🔄 Automatic Event Tracking: Clicks, page views, form interactions, and navigation
• 🌍 Geographic Detection: Automatic location detection with fallback handling
• 🖥️ Device & Browser Detection: Comprehensive browser, OS, and device type identification
• 📱 Responsive Tracking: Window size and device type monitoring
• 🔒 Privacy-First: Local storage with cookie fallback for user identification
• 🔄 Queue Management: Built-in API request queuing and retry logic
• 👤 User Identity Management: Associate events with specific users
• 📊 Session Management: Automatic session tracking and management

API Reference

Core Methods

questera.init()

Initializes the SDK, sets up event listeners, and tracks the initial page view.

questera.identify(userId, properties)

Associate current session with a specific user ID and optional user properties.

Tracking Control

questera.startTracking()

Enable event tracking (enabled by default).

questera.stopTracking()

Disable event tracking.

questera.resetIdentity()

Clear current user identity and generate new anonymous user.

Event Properties

questera.addEventProperties(properties)

Add properties that will be included with all future events.

questera.removeEventProperty(property)

Remove a specific event property.

questera.clearEventProperties()

Clear all event properties.

Page View Tracking

questera.trackPageview(path)

Manually track a page view.

questera.addPageviewProperties(properties)

Add properties to all page view events.

questera.removePageviewProperty(property)

Remove a specific pageview property.

questera.clearPageviewProperties()

Clear all pageview properties.

Manual Event Tracking

questera.trackClick(selector, properties)

Manually track click events.

questera.trackEntry(selector, value, properties)

Track form field entries.

questera.trackSelect(selector, value, properties)

Track select dropdown changes.

Utility Methods

questera.getUserId()

Get current user ID.

questera.getSessionId()

Get current session ID.

questera.getIdentity()

Get complete identity information (returns: { userId, sessionId, userProperties }).

questera.onReady(callback)

Execute callback when SDK is ready.

Automatic Tracking

What Gets Tracked Automatically

1. Page Views: Navigation, history changes, and initial page loads
2. Clicks: Interactive elements (buttons, links, clickable elements)
3. Form Interactions:
   • Text input and textarea entries (on blur)
   • Select dropdown changes
   • Radio button selections
4. Session Management: Automatic session creation and cleanup

Smart Element Detection

The SDK automatically identifies trackable elements based on:

• Interactive tags (button, a)
• Elements with click handlers
• Elements with cursor: pointer CSS
• Elements with tabindex attribute
• Elements with ARIA roles (button, link)
• Elements with data-track-id attributes

Data Collection

Each event automatically includes:

• Browser Information: Name and version
• Device Details: Type (Desktop/Mobile/Tablet) and platform
• Geographic Data: City, region, country, currency
• Page Context: URL, title, referrer, hash
• Window Information: Dimensions and viewport data
• User Context: Session ID, user ID (if identified)
• Element Context: CSS selectors, text content, data attributes

Data Attributes

data-track-id

Add this attribute to elements for better tracking identification. The tracking data will include this ID for easier event identification.

Privacy & Storage

• User IDs: Stored in localStorage with cookie fallback
• Session IDs: Stored in sessionStorage with cookie fallback
• Geographic Data: Cached locally to reduce API calls
• Cookie Expiration: 365 days for persistent data
• Session Cleanup: Session cookies cleared on page unload

Error Handling

The SDK includes built-in error handling for:

• Network failures
• API errors
• Geographic detection failures
• Queue processing errors

Browser Support

• Modern browsers with ES6+ support
• Chrome, Firefox, Safari, Edge
• Mobile browsers (iOS Safari, Chrome Mobile)
• Requires crypto.getRandomValues() for UUID generation

Troubleshooting

Events Not Showing Up

1. Check API key and entity ID are correct
2. Verify network connectivity to API endpoints
3. Check browser console for error messages
4. Ensure tracking is enabled: questera.startTracking()

Geographic Detection Issues

• The SDK will fall back to "Unknown" values if geographic API fails
• Geographic data is cached locally after first successful request

Element Not Being Tracked

• Ensure element has interactive properties (click handler, cursor: pointer, etc.)
• Add data-track-id attribute for better identification
• Check if element has useful data (text content, classes, etc.)