Pixel SDK Update - July

Pixel Version 1.3.7 Release Notes

 Release Notes: Pixel SDK Update

Version: 1.3.7

Overview

This is a major update to the Pixel SDK, focused on providing more granular control, smarter data collection, and increased robustness. We've introduced powerful new configuration options for click tracking, enriched the data captured for almost every event, and implemented foundational improvements for performance and stability, including client-side rate limiting and support for multiple SDK instances.

This update is fully backward compatible. We've maintained the existing configure() method while introducing enhanced functionality through a new configureAsync() method.


✨ New Features

  • Advanced Click Tracking Configuration (clickConfig)

  • You now have fine-grained control over what clicks are tracked. This can be configured via data- attributes on the <script> tag or programmatically.

  • New Script Attributes:

    • data-click-links="false": Disables tracking of <a> tag clicks.

    • data-click-buttons="false": Disables tracking of <button> and similar elements.

    • data-click-selectors=".track-me, #important-div": A comma-separated list of CSS selectors to explicitly track clicks on.

  • Programmatic Configuration: Pass a clickConfig object to PixelSDK.configure() or use the new PixelSDK.configureClickTracking() method.

  • Client-Side Rate Limiting

  • To prevent accidental event flooding and protect server resources, the SDK now includes a rate limiter. By default, it allows a maximum of 100 events per minute from a single client. This protects against issues like tight loops or buggy custom event triggers.

  • Multiple SDK Instance Support

  • The SDK now supports running multiple, independent pixel instances on the same page without conflicts. Each instance is namespaced to avoid overwriting the global window.PixelSDK object if it already exists.

  • Click Debouncing

  • To prevent a single user action (like a double-click) from generating multiple redundant events, clicks on the same element are now debounced by default (1000ms).

🚀 Enhancements & Improvements

  • Overall Data Enrichment: Nearly all tracking events have been enhanced to capture more valuable contextual data.

  • Initialization:

  • The SDK now uses document.currentScript to find its own <script> tag, which is significantly more robust than the previous method of querying by a fixed ID. A fallback and warning are in place for environments where this is not supported.

  • Element Information (getElementInfo):

  • Captured element data is now much richer, including className, href, type, role, aria-label, and all data-* attributes, providing deeper insight into user interactions.

  • Text content from elements is now intelligently trimmed to prevent overly large payloads.

  • Click Tracking (trackAllClicks):

  • In addition to the new configuration, the tracker now captures x/y coordinates of the click.

  • It now uses heuristics to identify "button-like" elements (e.g., those with style.cursor === 'pointer') for more comprehensive tracking of modern web interfaces.

  • Form Submissions (trackAllFormSubmissions):

  • Enhanced PII Filtering: The list of excluded field names is more comprehensive (credit_card, social_security) and the matching is now case-insensitive and checks for substrings, offering better protection.

  • Data Truncation: Long text values in form fields are now automatically truncated to 100 characters.

  • More Metadata: Now captures the form's name, action URL, and method (GET/POST).

  • Other Event Trackers:

  • trackPageView: Now includes viewport (window.innerWidth) and screen (window.screen.width) dimensions.

  • trackDeepScroll: The scroll depth threshold is now configurable. The event is also debounced to fire only after the user has stopped scrolling, improving accuracy.

  • trackExitIntent: Detects when users are about to leave the page by monitoring mouse movement toward the browser's top edge, capturing valuable exit behavior data.

  • trackFileDownloads: The default list of tracked file extensions has been greatly expanded. It now also captures the filename, file type, and the visible link text.

  • trackIdleUser: Now listens for a wider range of activity events (scroll, click, touchstart) for more reliable idle detection.

  • trackVideoEngagement: Now correctly handles and tracks multiple <video> elements on a single page and collects more detailed metadata like videoId, src, currentTime, and duration.

💡 Recommended Changes

While this update maintains full backward compatibility, we recommend adopting the following improvements for enhanced functionality:

  1. Migration for Existing configure() Users:

  • If you are currently using PixelSDK.configure() in your code, we recommend migrating to PixelSDK.configureAsync() for enhanced functionality.

  • The configure() method was historically used for basic SDK setup and initialization. In previous versions, it handled configuration synchronously without analytics integration.

  • The existing configure() method now shows a deprecation warning and skips analytics integration (GA4, Clarity) for performance while maintaining backward compatibility.

  • If you don't currently use configure() in your code, no action is required - the SDK auto-initializes with full functionality.


// If you currently have this (deprecated but still works)

Example
PixelSDK.configure({

  globalParams: { customParam: 'value' },

});

// Recommended migration for existing configure() users

Example
async function initializePixel() {

  await PixelSDK.configureAsync({

    globalParams: { customParam: 'value' },

  });

}

initializePixel();

  1. Improved Click Tracking Configuration:

  • The default click tracking behavior now intelligently targets meaningful interactive elements instead of capturing all clicks.

  • If you need to track clicks on custom elements, use the new configuration options.

  • This change improves performance and data quality by reducing noise from non-interactive element clicks.

🗒️ Developer Notes & Usage Examples

Example: Configuration via Script Tag

To track only clicks on elements with the class product-card and disable default link/button tracking, modify your script tag like this:


Example
<script

  id="delivr-ai"

  src="https://your-endpoint/pixel.js"

  data-auto-init="true"

  data-click-links="false"

  data-click-buttons="false"

  data-click-selectors=".product-card"

  async

></script>

Example: Programmatic Configuration

You can achieve the same result by configuring the SDK with JavaScript.


// Ensure the SDK is loaded before calling this

Example
async function setupPixel() {

  await PixelSDK.configureAsync({

    clickConfig: {

      trackLinks: false,

      trackButtons: false,

      trackCustomSelectors: ['.product-card', '#newsletter-signup'],

      debounceMs: 500, // Optional: override default debounce time

    },

  });




  console.log('Pixel configured!');

}




setupPixel();